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Notices 


Any reference to an IBM licensed program is not intended to state or imply that only 
IBM’s licensed program may be used. Any functionally equivalent product, program, 
or service that does not infringe any of IBM’s intellectual property rights can be used 
instead of the IBM product, program, or service. Evaluation and verification of 
operation in conjunction with other products, programs, or services, except those 
expressly designated by IBM, is the user’s responsibility. 

IBM might have patents or pending patent applications covering subject matter in this 
document. The furnishing of this document does not give you any license to these 
patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
500 Columbus Avenue 
Thornwood, NY 10594 USA 

This publication contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


Trademarks 

The following terms are trademarks of the IBM Corporation in the United States or 
other countries: 

BookManager 
Common User Access 
CUA 
IBM 

IBMLink 
Library Reader 
Open Class 
OS/2 

OS/2 Warp 
Presentation Manager 
PROFS 
VisualAge 
WorkFrame 
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Workplace Shell 

The following term is a trademark of another company: 
C++ American Telephone & Telegraph Company 
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About This Book 

Welcome to Visual Builder—the quickest and easiest way to create applications using 
the C++ programming language! This book. Visual Builder User’s Guide, introduces 
parts, tools, and features that you can use to build Visual Builder applications. 

Visual Builder is a tool provided by VisualAge C++. It is based on the 
construction-from-parts paradigm, a software development paradigm in which 
applications are assembled from reusable and existing software components, called 
parts. You can extend Visual Builder by adding your own reusable, custom parts and 
then using these parts in your applications as you need them. 

Visual Builder gets you started by providing a set of parts as well as interactive 
visual programming tools to work with those parts. You create your applications by 
visually assembling and connecting these prefabricated parts. In many cases, you do 
not even have to write any code. 


Who Should Use this Book 

Programmers who want to develop C++ applications using Visual Builder should read 
this book. Knowledge of object-oriented (OO) concepts, although not required unless 
you are interested in extending the Visual Builder parts to include your own parts, is 
highly recommended. This product incorporates OO concepts and knowledge of them 
will allow you to get the maximum use from the product, as well as an understanding 
of the terminology used in this book. 


How to Use this Book 

If you are new to Visual Builder, read through the first section completely. If you 
have used Visual Builder before, you can skim that section. 

You will find shortcut techniques and other tips wherever you see • 

This book refers to sample code that might have been modified after this book went 
to press. For the most current information, refer to the sample files used in this book. 
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How This Book Is Organized 

This book is grouped into the following parts and appendixes: 

• Part 1, “Getting Started,” 

The first part introduces you to Visual Builder and its concepts. It also shows 
you how to start Visual Builder, walks you through your first application, and 
tells you how to set up a WorkFrame project to use Visual Builder. 

• Part 2, “Touring Visual Builder” 

This part shows you how to work with .vbb files, the files you store your parts 
in, and provides an overview of the Visual Builder editors. 

• Part 3, “Developing Visual Builder Applications” 

In this part, you travel through various aspects of application development and 
see how you can begin developing your own Visual Builder applications. You 
also learn how to use the Visual Builder window to work with parts. 

• Part 4, “Extending Visual Builder Applications” 

This part provides information that pertains to special aspects of application 
development that may not apply to all applications. 

• Glossary and Reader’s Comment Form 

The book ends with a glossary and information on sending us your comments 
and questions about Visual Builder. 
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Highlighting Conventions 

This book uses the following highlighting conventions: 


Highlighting 

Element 

Example 

Bold 

Key interface items in code 

Select Tools from the menu 


listings. Areas in code 
examples that are described in 
accompanying text 

bar. 

Monospace 

C++ coding examples, text that 

The following code from the 


the user enters, and messages 

IAddress illustrates ... 


(within text) 

The street member function 

returns the current street. 

Italics 

Emphasis of words, first time a 

stored in persistent objects 


glossary term is used 

Refer to Object-Oriented User 


Titles of books 

Interface Design - IBM 

Common User Access 

Guidelines. 


How to Get Help 

There are three kinds of online information available to you while you are using 

VisualAge C++: 

Online documents 

These are complete documents, like the one you are reading now, 
presented online. These documents contain detailed information on the 
different aspects of VisualAge C++. For your convenience, the online 
documents are presented in two formats: 

• Standard format. See “Getting Help Inside VisualAge C++” on 
page xv for instructions on opening standard format documents from 
inside VisualAge C++. See “Getting Help from the Command Line” 
on page xvi for instructions on opening standard format documents 
from the command line. The following documents are available in 
standard format: 

- Read Me First! 

- Welcome to VisualAge C++ 

- User's Guide and Reference 

- Programming Guide 

- Visual Builder User's Guide 

- Visual Builder Parts Reference 

- Building VisualAge C++ Parts for Fun and Profit 
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- Class Library User's Guide 

- Class Library Reference 

- IBM Dictionary of Computing 

- C Library Reference 

- Editor Command Reference 

• BookManager format. See “BookManager Books” on page xvi for 
details on how to access online documents in this format. For a list 
of the VisualAge C++ documents that are available in BookManager 
format, see “The VisualAge C++ BookManager Library” on 
page 317. 

Contextual help 

Contextual help is available throughout VisualAge C++. This help tells 
you all about the elements that you see in the interface, including menus, 
entry fields, and pushbuttons. 

How Do I help 

Many of the common tasks that you want to perform with 
VisualAge C++ are described in How Do I help. The How Do I help for 
a task gives you step-by-step instructions for completing the task. There 
is overall How Do I help for VisualAge C++, as well as individual task 
lists for each of its components. 

Getting Help Inside VisualAge C++ 

All three kinds of help are available directly within the VisualAge C++ interface: 

• To get general contextual help for the component of VisualAge C++ that you are 
using, press FI anywhere in the window. 

• To get contextual help on a particular menu, menu item, or button, highlight the 
element and press FI. 

• To get access to all of the help information that is available to you in a particular 
window, click on Hel p in the menu bar at the top of the window. This menu 
includes the following selections: 

- Hel p Index, an alphabetical list of all of the help topics that are available 
from this window 

- General Hel p, overall help for the window 

- Using Help, general information about the help facility 

- How Do I ..., the How Do I help for the component 

- Product Information, a dialog that shows the level of VisualAge C++ 
being used 
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• To get detailed information, open the Information folder in the VisualAge C++ 
folder. In this folder you will find icons for a variety of online documents that 
describe, in detail, the different aspects of VisualAge C++. To open a particular 
online document, double click on its icon. 

How to Use the How Do I? Help 

The Help choice on the menu bar in each window that Visual Builder displays 
contains a menu item called How Do I? When you select this menu item. Visual 
Builder displays a list of tasks that you can perform. 

To use the list of tasks, double-click on a task and Visual Builder displays a list of 
steps that tells you how to perform that task. 

To close the list of tasks, you can do either of the following: 

• Select the Exit push button at the bottom of the window. 

• Press F3. 

• Click on the window using mouse button 2 and select Exit from the pull-down 
menu that is displayed. 

Getting Help from the Command Line 

If you want, you can look at the online documents by issuing the view command. 

The installation routine stores the online document files in the \ I BMCPP\HELP directory. 
To view the IBM Dictionary of Computing, for example, make C:\IBMCPP\HELP your 
current directory (substituting the drive where you installed VisualAge C++ for C:) 
and enter the following command: 

VIEW CPPLNG.INF 

If you want to get information on a specific topic, you can specify a word or a series 
of words after the file name. If the words appear in an entry in the table of contents 
or the index, the online document is opened to the associated section. For example, if 
you want to read the section on operator precedence in the IBM Dictionary of 
Computing, you can enter the following command: 

VIEW CPPLNG.INF OPERATOR PRECEDENCE 

BookManager Books 

In addition to standard format, the online documents are also available in 
BookManager format. In this format they can be read using the BookManager 
READ/2 product (program number 73F6023). VisualAge C++ comes complete with 
the IBM Library Reader, which allows you to read BookManager books without 
having to install the complete BookManager READ/2 product. Like the standard 
format, the BookManager format features hypertext links and a search utility. 
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Getting Started 


Part 1. Getting Started 

This part describes Visual Builder, its benefits, and its key concepts. It also shows 
you how to start Visual Builder, walks you through your first application, and tells 
you how to set up a WorkFrame project to use Visual Builder. 


Chapter 1. What Is Visual Builder? . 3 

What Are the Benefits of Using Visual Builder? . 3 

What Are the Key Concepts? . 4 

Chapter 2. Creating a Simple Visual Builder Application . 7 

Creating the To-Do List Application . 7 

Chapter 3. Setting Up and Starting Visual Builder .25 

Setting Up Your WorkFrame Project to Use Visual Builder .25 

Starting Visual Builder .26 


© Copyright IBM Corp. 1992, 1995 1 














Getting Started 


2 Visual Builder User’s Guide 



Getting Started 



What Is Visual Builder? 


Visual Builder is a visual programming tool that can help you create object-oriented 
(OO) programs using the C++ programming language. With Visual Builder, you can 
create applications faster and easier than you ever could using a text editor. Visual 
Builder provides a powerful visual editor, the Composition Editor, which enables you 
to create complete applications, often without writing code. 


What Are the Benefits of Using Visual Builder? 

With Visual Builder, you can quickly create applications with advanced graphical user 
interfaces (GUIs). You can use Visual Builder to build OO applications by 
assembling and connecting parts. 

Visual Builder is part of VisualAge C++, a state-of-the-art C++ application 
development product that includes the IBM Open Class Library, WorkFrame, code 
browsing and editing tools, and a sophisticated debugger. 

With Visual Builder, you can adopt OO technology immediately and learn to use it at 
the pace that is best for you. Its benefits include the following: 

• When you work with Visual Builder’s visual programming tools, you are creating 
OO applications. 

• You can use Visual Builder to enhance and extend your applications because 
Visual Builder supports C++, an OO programming language. 

• You can also access other logic written in C and C++ using Visual Builder’s 
support for external C and C++ program logic. 

• You can shorten your application development cycle time considerably by 
creating reusable parts. 

• You can change the way a part does its work without affecting its external 
interface by encapsulating your application into parts. Encapsulating your 
application into parts also helps you deploy your business logic where it needs to 
be. Critical calculations can be moved into a dynamic link library. 

• By its nature. Visual Builder caters to all skill levels, so that programmers using 
Visual Builder can build not only simple applications but also complex ones. 
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What Are the Key Concepts? 

Before we continue any further, let’s look at some key Visual Builder concepts. 

Parts 

In Visual Builder, a part is a C++ class that, in addition to the usual elements of a 
C++ class, includes a well-defined part interface. The part interface defines how the 
part can interact with other parts. 

Three kinds of features make up a part interface. The following list provides a brief 
description of each kind: 

attributes The logical data, often stored in data members, that other parts can 

access. This data can represent any logical property of a part, such as 
the balance of an account, the size of a shipment, or the text of a 
push button. 

actions Services or operations that a part can perform. Actions, such as 

placing an order or displaying a window, can be triggered by 
connections from other parts. 

events Signals that a part can send to notify itself or other parts that a 

change has occurred. When events are connected to attributes, 
actions, or member functions of other parts, the connections monitor 
these events and trigger the target features when the events occur. 

For example, when a push button’s buttonClickEvent feature is 
connected to an action of another part, the other part’s action is called 
when the push button is clicked. 

To get you started. Visual Builder provides a set of base parts for you. These parts 
are included in the vbbase.vbb file, which Visual Builder loads each time it is started. 
The parts in this file are based on the classes in the IBM Open Class Library. Visual 
Builder does not allow you to modify these parts, but you can create parts of your 
own by subclassing or using these parts in parts that you create. 

Connections 

To define how the parts interact with each other, you can make the following kinds of 
connections. The definitions that follow apply to most cases in which these 
connections are used. Exceptions and special cases are noted in Chapter 9, “Learning 
to Use Connections” on page 167. 

Attribute-to-attribute Connections that link two data values together 

so that when one changes, the other changes, 
too. 
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Event-to-attribute Connections that change the value of an 

attribute when a certain event occurs. 

Event-to-action Connections that start an action when a certain 

event occurs. 

Connections that start an action whenever an 
attribute’s event identifier is signalled. 

Connections that call a member function 
whenever a certain event occurs. 

Attribute-to-member function Connections that call a member function 

whenever an attribute’s event identifier is 
signalled. 

Custom logic Connections that call your customized C or C++ 

logic whenever an event or an attribute’s event 
identifier is signalled. 

Parameter Connections that provide a parameter value for 

an action or member function. The parameter 
value can be provided by connecting a 
parameter to an attribute, an action, a member 
function, or custom logic. 


Attribute-to-action 

Event-to-member function 


Source code generation 


Visual Builder can generate C++ code for the GUI that you design in the 
Composition Editor, as well as for all of the connections that you make between 
parts. It can also generate C++ code for any new parts that you create. You can then 
use the code that Visual Builder generates when building your application. This 
capability allows you to concentrate on what your application does instead of 
spending time writing code for the GUI and its connections. 


Besides saving you time and effort, additional advantages of letting Visual Builder 
generate your code instead of writing it yourself include the following: 

• Easier code modifications. 

Do you want to replace a multiline entry field with a list box? Delete the entry 
field, drop the list box in its place, make any necessary connections, and 
regenerate the code. That’s all. 

• Fewer errors. 

Because Visual Builder can generate the majority of the code for your 
application, there is less opportunity for human errors, such as typographical and 
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syntax errors, to creep into your code. That means you spend less time 
debugging your code for minor errors. 

• Support for pre-existing C and C++ code. 

Using Visual Builder's Class Editor, you can specify files that contain existing C 
or C++ code that you want to use in your application. Then, when you generate 
the code for your application, those files are included. 

In addition, you can create .vbe files that contain information about your C++ 
classes. You can then import that information into Visual Builder so that you 
can use those classes as parts. Refer to Building VisucdAge C++ Parts for Fun 
and Profit for information about using .vbe files. 

• Standard format. 

Another advantage is that a standard format is applied to all generated code. The 
code that Visual Builder generates is uniformly structured, indented, and 
commented. 


6 Visual Builder User’s Guide 



Getting Started 



Creating a Simple Visual Builder Application 


The best way to learn about Visual Builder is to see how you can use it. The 
following sections take you through an example of how you might use Visual Builder 
to develop an application for creating and maintaining a simple to-do list. Figure 1 
shows what the application looks like when it is finished. 


To-Do List 


To-do item 


□ 



Add 


Remove 


Figure 1. Finished To-Do List Application 


Creating the To-Do List Application 

Creating the To-Do List application consists of the following steps: 

• Starting Visual Builder for the To-Do List application 

• Creating a new visual part for the To-Do List application 

• Placing parts in the application window 

• Resizing and aligning the parts 

• Connecting the parts 

• Generating the C++ code for your application 

• Building the application 

• Running the application 

• Exiting the Composition Editor and Visual Builder 
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Starting Visual Builder for the To-Do List Application 

Before you create the To-Do List application, start Visual Builder. For this sample 
application, start Visual Builder from the Tools folder, as follows: 

1. Double-click on the VisualAge C++ folder icon on your desktop. 

The VisualAge C++ folder opens. 

2. Double-click on the Tools folder icon. 

The Tools folder opens. 

3. Double-click on the Visual Builder icon. 

Visual Builder displays the Visual Builder window, as shown in Figure 2. 


Visual Builder - D:\IBMCPP\WORKING\ 


File Part Edit Options Help 
Loaded Part Files 
VBBase.vl)!) 


Visual Parts Monvisual Parts 


Figure 2. Visual Builder Window 

Now it is time to create a new visual part for the To-Do List application. 
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Creating a New Visual Part for the To-Do List Application 

Before you create your new visual part for the To-Do List application, set the option 
for generating make files by selecting Options—^Generate make files. Otherwise, 
when you finish the application and generate the code. Visual Builder will not 
generate the make file. By selecting this option now, you will not have to come back 
to the Visual Builder window to select it later. 

The next thing to do when creating the To-Do List application is to create the main 
part, a new visual part, as follows: 

1. Select Part-^New. 

Visual Builder displays the Part — New window, as shown in Figure 3. 



Figure 3. The Part — New Window 

The Part — New window provides the following fields in which you can enter 
information about your part: 

• The Class name field, where you enter the name of your part. Each 
composite part must have a name. 

For the To-Do List application, enter the following: 

ToDoLi st 

• The Description field, where you enter a description of your part. 

For this example, enter the following: 

The To-Do List application 

• The File name field, where you enter the name of the .vbb file in which you 
want Visual Builder to store your part. 

For this example, you can either leave this field blank or enter the following: 
ToDoList.vbb 
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This causes Visual Builder to store the ToDoList part in a file named 
todolist.vbb. If you leave this field blank. Visual Builder uses the part name 
as the name of the .vbb file by default, so the result is the same. 

• The Part type field, where you indicate the type of part. This field initially 
contains Visual part. However, you can specify a different type of part to 
create by selecting one from the field’s drop-down list box. 

For this example, do not select a different part type because you want to 
create a visual part for the To-Do List application. 

• The Base class field, where you specify the class that you want to be the 
base class of the part that you are creating. The base class is the part that 
part you are creating inherits attributes, events, and actions from. The Base 
class field contains the default base class name of IFrameWindow, which 
Visual Builder uses when you specify that you want to create a new visual 
part. 

For this example, leave IFrameWindow as the base class. 

2. Select the Open push button to create a visual part named ToDoList whose 

parent is IFrameWindow. This causes Visual Builder to display the Composition 
Editor. For more information about the Composition Editor, see “The 
Composition Editor” on page 42. 

If you look back at the Visual Builder window, you see that the file todolist.vbb is 
now included in the list of loaded files. This file was created for you when you 
selected the Open push button in the Part — New window. 

Before you place any parts in the application window, first edit its title. 

Changing the title of the To-Do List application window 

The new visual part that you just created contains an IFrameWindow* part. This will 
be the To-Do List application window. Change the title of this window by doing the 
following: 

1. Hold down the Alt key. 

2. Click on the title bar with mouse button 1. 

3. Type the new title text, such as To-Do List. 

4. Press Shift+Enter after you have changed the window title. 
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Placing Parts in the Application Window 

Now that you have created your new visual part and edited the title of the application 
window, it is time to place the other parts of the To-Do List application in the 
application window. 

Placing a static text part in the window 


The To-Do List application needs two static text parts. Follow these steps to place 
the first static text part in the To-Do List application window: 


1. Select 



, the Data entry category, from the row of icons on the left-hand 
side of the parts palette. 


A A 

2. Select £ ^ , the IStaticText* icon, from the row of icons on the right-hand 

side of the parts palette. 

When you move the mouse pointer over the free-form surface, you see that it has 
changed to crosshairs. This means the mouse pointer is loaded with the 
IStaticText* part. 

3. Place the crosshairs in the upper-left corner of the To-Do List application 
window’s client area and click mouse button 1. 


A static text part is placed in the window. 

4. Change the text of the static text part to To-do item. Use the same method for 
changing text that you learned previously when you changed the title of the 
To-Do List application window. 


Placing an entry field in the window 


The To-Do List application needs an entry field part. Follow these steps to place an 
entry field part in the To-Do List application window: 


1. Select 



, the Data entry category, from the row of icons on the left-hand 
side of the parts palette. 


the IEntryField* icon, from the row of icons on the right-hand 


2. Select 
side of the parts palette. 

3. Place the crosshairs beneath the first static text part and click mouse button 1. 
The entry field part is placed beneath the static text part. 
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Placing another static text part in the window 


The To-Do List application needs another static text part. Follow these steps to place 
and modify this part: 

1. Place the second static text part in the To-Do List application window. Use the 
same method for placing a static text part that you learned previously when you 
placed the first static text part in the To-Do List application window. 

2. Change the text of the static text part to To-do 1 ist. Use the same method for 
changing text that you learned when you changed the title of the To-Do List 
application window. 

Placing a list box in the window 


Because the to-do list is to consist of a list of text strings, you want to store that list 
in an IListBox* part. Follow these steps to place a list box part in the To-Do List 
application window: 


1. Select 


IB 


the Lists category, from the row of icons on the left-hand side 


of the parts palette. 


2. Select 


__ 


, the IListBox* icon, from the row of icons that Visual Builder 


displays on the right-hand side of the parts palette. 

3. Place the crosshairs below the second static text part and click mouse button 1. 
The list box part is placed beneath the second static text part. 


Placing the push buttons in the window 


The To-Do List application needs two push buttons, one for adding items to the list 
and one for removing items from the list. Follow these steps to place two push 
button parts in the To-Do List application window: 


1 . 


13 


Select 


side of the parts 


, the Buttons category, from the row of icons on the left-hand 
palette. 


2. Select I I , the IPushButton* icon, from the row of icons on the right-hand 

side of the parts palette. 
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3. Place the crosshairs below the lower-left corner of the list box and click mouse 
button 1. 

The first push button part is placed in the window. 

4. Select the IPushButton* icon again. 

5. Place the crosshairs to the right of the first push button and click mouse 
button 1. 

The second push button is placed in the window. 

6. Change the text of the first push button to Add. Use the same method you used 
to change the text in the title bar. 

7. Change the text of the second push button to Remove. 

Resizing and Aligning the Parts 

Now that you have placed all of the parts you need in the application window, it is 
time to resize and align them. When you have finished, your application window 
should look like Figure 1 on page 7. 

Matching the width of the list box to the width of the entry field 

Follow these steps to match the width of the list box to the width of the entry field: 

1. Move the mouse pointer over the list box. 

2. Press and hold mouse button 1. 

The selection handles appear at the four corners of the list box. 

3. While holding down mouse button 1, move the mouse pointer to the entry field. 

The selection handles on the list box become hollow and black selection handles 
appear on the four corners of the entry field. This means that both parts are 
selected, but the entry field is the anchor part. Therefore, any sizing actions 
performed using the tool bar cause the list box to match the size of its anchor 
part, the entry field. 

i i 

4. Select M M , the Match Width tool, from the row of icons on the tool bar, 
located beneath the menu bar. 

The width of the list box changes to match that of the entry field. 
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Matching the width of the Add push button to that of the Remove push button 

Using the techniques you learned in the preceding steps, match the width of the Add 
push button to that of the Remove push button. 

Dragging and dropping parts in the application window 

Before you align the parts, you might want to drag and drop some of them to put 
them in closer proximity to each other. For example, you might want the static text 
parts to be closer to the parts that they label. Follow these steps to drag and drop the 
parts in the application window: 

Note: The following instructions are written for dragging and dropping multiple 
parts simultaneously. If you just want to drag and drop one part at a time, 
you can skip the first step. 

1. Select all of the parts you want to drag using the technique you learned 
previously when matching the width of the list box to the width of the entry 
field. 

2. Move the mouse pointer over one of the parts that you selected to drag. 

3. Press and hold mouse button 2 and move the mouse cursor. 

Visual Builder displays an outline of the parts that you are dragging. 

4. Move the outline to the place where you want to drop the parts and release 
mouse button 2. 

The parts are moved to their new location. 

Resizing the application window 


At this point, the parts in the application window are closer to the left window border 
than to the right window border. Follow these steps to resize the application window: 

1. Select the application window by clicking mouse button 1 on the title bar. 

2. Move the mouse pointer over the selection handle on the lower-right corner of 
the application window. 

3. Press and hold mouse button 1. 

4. Resize the application window by dragging the mouse pointer towards the left 
until the right border of the application window is approximately the same 
distance from the entry field and list box as the left border is. 


O 


To size the window in only one direction, either horizontally or vertically, 
hold down the Shift key while dragging the mouse pointer. 
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Centering the entry field and list box within the application window 


The entry field and list box need to be centered within the application window. 
Follow these steps to center them: 


1. Select the entry field. 


□ On 

2. Select , the Distribute Horizontally tool, from the row of icons on the 

tool bar. 


Visual Builder centers the entry field between the left and right borders of the 
application window. 

3. Select the list box and then the entry field, making the entry field the anchor part. 
Use the multiple part selection technique you learned previously. 


4. Select 


cp 

[=izz 

cb 


, the Align Center tool, from the row of icons on the tool bar. 


The list box is centered beneath the entry field. 


Aligning the static text, entry field, and list box parts so their left edges are even 


The static parts need to be aligned evenly with the left edges of the entry field and 
list box. Follow these steps to align them: 

1. Select the first static text part and then select the entry field, making the entry 
field the anchor part. Use the multiple part selection technique you learned 
previously. 




2 . 

3. 


Select 


!=□ 


, the Align Left tool, from the row of icons on the tool bar. 
The first static text part is aligned even with the left edge of the entry field. 
Repeat steps 1 and 2 for the second static text part and the list box. 

The second static text part is aligned even with the left edge of the list box. 


Aligning the top edges of the push buttons 


The push buttons need to be aligned so that their top edges are even. Follow these 
steps to align them: 

1. Select the Add push button and then select the Remove push button. Use the 
multiple part selection technique you learned previously. 
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2. Select I H I , the Align Top tool. 

Visual Builder aligns the Add push button even with the top of the Remove push 
button. 


tush buttons evenly across the application window 


The push buttons need to be evenly spaced across the width of the application 
window. Follow these steps to space them: 

1. Select both push buttons. You can make either push button the anchor part. Use 
the multiple part selection technique you learned previously. 

□ On 

2. Select 1 1 1 , the Distribute Horizontally tool. 

Visual Builder spaces both push buttons evenly across the application window. 



The push buttons need to be centered between the bottom edge of the list box and the 
bottom border of the application window. Follow these steps to center them: 

1. Select both push buttons. You can make either push button the anchor part. Use 
the multiple part selection technique you learned previously. 

2. Move the mouse pointer over either push button. 

3. Press and hold mouse button 2, and position the push buttons midway between 
the bottom edge of the list box and the bottom window border. 

4. When the push buttons are in place, release mouse button 2. 

Your application should now look like the one shown in Figure 1 on page 7. 

Connecting the Parts 

Now it is time for you to connect the parts so that your application can add items to 
and remove items from the to-do list. You need to connect the push buttons to the 
list box and entry field. The following steps show you how to do this. 
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Before you start connecting parts, it is a good idea to make sure none of 
your parts is selected. Otherwise, the correct pop-up menus may not 
appear. To do this, hold down the Ctrl key, point to each item that is 
selected, and press mouse button 1. When the selection handles disappear, 
you know that the part is no longer selected. 

Connecting the Add push button to the list box 

The connection between the Add push button and the list box provides the 
information your application needs to add items to the list box. 

1. With the mouse pointer over the Add push button, click mouse button 2. 

A pop-up menu is displayed. 

2. Select Connect. 

A cascaded menu, called the connection menu, of the Add push button is 
displayed. 

3. Select the buttonClickEvent feature. 

Selecting the buttonClickEvent feature means that you want something to happen 
whenever a user clicks this push button. The mouse pointer changes to look like 
a spider, indicating that it is ready for you to select another feature. 

4. Move the mouse pointer to the list box and click mouse button 1. 

A pop-up menu is displayed showing the connection menu of the list box. 

5. Select the addAsLast action. 

Selecting the addAsLast action means that you want new items to be added to the 
end of the to-do list whenever a user clicks the Add push button. The 
connection is shown in Figure 4. 



Add 


Remove 


Figure 4. The Connection between the Add Push Button and the List Box 


The line connecting the Add push button to the list box is dark green. It points 
from the push button to the list box, showing that the event that occurs when the 
push button is selected will cause the list box to perform an action. 
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Notice that the connection line is dashed instead of solid. A dashed line means 
that the connection is incomplete. The connection is supposed to add something 
to the list box when the Add push button is clicked, but you have not yet 
supplied what needs to be added. The next step does that. 

6. Move the mouse pointer to the dashed connection line between the Add push 
button and the list box. 

A hollow box appears over the connection to let you know that the connection 
will be affected by the next mouse button click. 

7. To take a shortcut to display connection menus, hold down the Alt key and click 
mouse button 2. 

The pop-up menu for the connection is displayed. 

8. Select the text parameter. 

The text parameter is the reason the connection line is dashed. You need to give 
this parameter a value. 

9. Move the mouse pointer over the entry field, and click mouse button 1. 

Visual Builder displays the connection menu for the list box. 

10. Select the text attribute. 

Selecting the text attribute here means that you want to pass the text that a user 
enters in the entry field to the text parameter of the addAsLast action. This text 
string is added to the end of the to-do list whenever the addAsLast action is 
called, which occurs whenever the Add push button is clicked. The completed 
connection is shown in Figure 5. 


To-do item 



Figure 5. The Completed Connection for the Add Push Button 
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The line connecting the entry field to the connection between the Add push 
button and the list box is violet. The solid arrow head points to the entry field, 
showing that the text attribute is the target of the connection. 

The hollow arrow head points to the connection line, indicating that the text 
parameter of the addAsLast action is the source of the connection. When the text 
parameter needs a value, which occurs when a user clicks on the Add push 
button, the connection invokes the get member function of the entry field’s text 
attribute. The value of that attribute (the text in the entry field) is returned to the 
text parameter and the addAsLast action puts the text string in the list box. 

Notice that both of the connection lines are solid. This means that the 
connection between the Add push button and the list box now has the 
information it needs to perform its function, so the connection is complete. 

Connecting the Remove push button to the list box 

The connection between the Remove push button and the list box provides the 
information your application needs to remove items from the list box. 

1. With the mouse pointer over the Remove push button, hold down the Alt key 
and click mouse button 2. 

Visual Builder displays the connection menu for the Remove push button. 

2. Select the buttonClickEvent feature. 

3. Move the mouse pointer to the list box and click mouse button 1. 

Visual Builder displays the connection menu for the list box. 

4. Select the remove action. 

Selecting the remove action means that you want your application to remove the 
selected item in the to-do list whenever a user clicks the Remove push button. 
Once again, the connection is incomplete. 

5. Move the mouse pointer to the connection between the Remove push button and 
the list box. 

6. Hold down the Alt key and click mouse button 2. 

Visual Builder displays the connection menu for the connection. 

7. Select the index parameter. 

The index parameter is the reason the connection line is dashed. You need to 
give this parameter a value. 

8. Move the mouse pointer over the list box and click mouse button 1. 

Visual Builder displays the connection menu for the list box. 
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9. Select the selection attribute. 

Selecting the selection attribute means that you want to pass the index of the 
selected item in the list box to the index parameter of the remove action. The 
remove action uses this index to determine which item to remove whenever the 
Remove push button is clicked. 

Making this connection completes your application. It should now look like the 
one shown in Figure 6. 


To-Do List 


To-do item 


To-do list 


° □ 


jt ^ 

Add Remove 


Figure 6. The Completed To-Do List Application 

Note: In the preceding figure, we changed the shape of the connection between 
the Remove push button and the list box to make it easier for you to see. 
You can do this by selecting the connection and dragging the middle 
selection handle. 

Now that you have made all of the connections, the next step is to generate your C++ 
source code. 

Generating the C++ Code for Your Application 

The first thing you must do to get your application ready to build is to generate the 
C++ code. This is a two-part process that consists of generating the source code for 
your new visual part and then generating the source code for your main() procedure. 

Generating the source code for your visual part 

To generate the C++ source code for your visual part, select File-^-Save and 
Generate-*Part source. 
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Another way to generate part code is to select ' , the Part Code 

Generation tool, on the tool bar. The results are the same. 


Visual Builder generates the following files in the working directory: 


todolist.cpp 

todolist.hpp 

todolist.h 

todolist.rc 


The C++ code for your ToDoList part. 

The C++ header file for your ToDoList part. 

The resource header file for your todolist.cpp file. 
The resource file for your todolist.cpp file. 


Generating the source code for your main!) function 

To generate the source code for your main() procedure, select File-^Save and 
Generate-^>main() for part. Visual Builder generates the following files in the 
working directory: 

todolist.app The main function for your application. 

Note: If you start Visual Builder from a WorkFrame project, the 
name of this file is vbmain.cpp. 

todolist.mak The make file that you specify when you build your application. 

You have now generated the C++ code for your application. The next step is to build 
the application. 


Building the Application 

Building your application consists of compiling and linking it. To build your 
application, do the following: 

1. Open an OS/2 window. 

2. Change to your Visual Builder working directory. 

3. Enter the following command: 
nmake todolist.mak 

This command produces the following files: 

todolist.exe The executable file for your application, 
todolist.map The application configuration map. 
todolist.o The object file for your application. 

Note: If you start Visual Builder from a WorkFrame project, 
the name of this file is vbmain.obj. 
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todolist.obj The object file for your part. Visual Builder provides a 
separate object module for your part that is used when 
compiling this part with other parts, 
todolist.res The binary resource file that is bound to todolist.exe. 

You have now built your application; the next step is to run your application. 

Running the Application 

To run your application from the same OS/2 command prompt from which you 
entered the nmake command, enter the following: 

todolist 

Once your application is running, experiment with it to make sure it works as you 
designed it. That is all there is to it! 

You can add a finishing touch to your application by creating an OS/2 program 
object. Create a program object from the OS/2 Templates folder, specifying the name 
todolist.exe as the program name and the directory that contains todolist.exe as the 
working directory. Once you have done this, you can run your application by simply 
double-clicking on the program object you just created. 
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Exiting the Composition Editor and Visual Builder 

To exit either the Composition Editor or Visual Builder, do either of the following. 

Note: When you exit Visual Builder, any changes you have made to the selections 
in the Options menu are saved. Therefore, if you want certain options to be 
selected or deselected the next time you start Visual Builder, be sure to select 
or deselect them before exiting Visual Builder. 

• Select File-*Exit. 

• Double-click on the system menu icon in the window. 

If you try to exit Visual Builder while one or more editor windows is open. Visual 
Builder displays a message asking if you want to close the editors and Visual Builder. 
You can select either of the following: 

• The OK push button to exit the windows. 

• The Cancel push button to cancel the exit request. 

If you select the OK push button with this message displayed or try to exit an editor 
and the open editor window contains unsaved changes. Visual Builder displays a 
message asking if you want to save the changes for each open editor before exiting. 
You can select either of the following: 

• The Yes push button to save the changes and exit. 

• The No push button to exit without saving the changes. 

• The Cancel push button to cancel the exit request. 
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Setting Up and Starting Visual Builder 


This chapter tells you how to do the following: 

• Set up your WorkFrame project to use Visual Builder 

• Start Visual Builder 


Setting Up Your WorkFrame Project to Use Visual Builder 

If you have created a WorkFrame project and will be running Visual Builder from the 
project folder, you should set up the project as follows before starting Visual Builder. 

Note: We recommend that you use a Project Smarts Visual Builder template in your 
WorkFrame project. Refer to the VisualAge C++ User’s Guide for 
information on how to do this. 

1. Open the settings notebook for the project folder by doing the following: 

a. Click on the project folder with mouse button 2. 

b. Select Open-*Settings. 

The settings notebook appears. 

2. Set the names of the executable file and the make file by doing the following: 

a. On the Target page, type the name that you want your executable file to 
have in the Name field. 

b. Type the name that you want your make file to have in the Makefile field. 

3. Set the directory in which your project files will be stored by doing the 
following: 

a. Select the tab for the Location OS/2 Files page. 

b. Type the full path for the directory in which you want to store your project 
files in the multiline edit field on this page. This is the directory in which 
Visual Builder puts the files for your application when you generate your 
source code. 

4. Inherit the settings of a C++ project by doing the following: 

a. Select the tab for the Inheritance page. 

b. Select the Add push button. 

A dialog is displayed in which you select the project whose settings you 
want to inherit. 
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c. Double-click on the Desktop directory in the Directory list box. 

d. Double-click on the VisualAge C++ 3.0 directory, also in the Directory list 
box. 

e. Select the C Set ++ Project file in the File list box. 

f. Select the Inherit push button. 

This puts all of the WorkFrame tools, including Visual Builder, that you 
need for a C++ project in the project’s pop-up menu, giving you easier 
access to them. 

5. Close the settings notebook. 

You are now ready to start Visual Builder. See “Starting Visual Builder” if you need 
information about doing this. 


Starting Visual Builder 

You can start Visual Builder in the following ways: 

• From the C/C++ window 

• From the Tools folder icon 

• From a WorkFrame Project folder 

Starting Visual Builder from the C/C++ window 

To start Visual Builder from the C/C++ window, do the following: 

1. Double-click on the icon for the VisualAge C++ folder. 

The folder opens. 

2. Double-click on the C/C++ Window icon. 

The C/C++ window opens. 

3. Type the following: 
i csvb 

4. Press the Enter key. 

Visual Builder displays the Visual Builder window, as shown in Figure 7 on 
page 27. 
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Visual Builder - D:\IBMCPP\WORKING\ 


File Part Edit Options Help 
Loaded Part Files 
VBBase.vbb 


□ 


Visual Parts 


Nonvisual Parts 


Figure 7 . Visual Builder Window 

Starting Visual Builder from the Tools folder 

To start Visual Builder from the Tools folder, do the following: 

1. Double-click on the icon for the VisualAge C++ folder. 

The folder opens. 

2. Double-click on the Tools folder icon. 

The folder opens. 

3. Double-click on the Visual Builder icon. 

Visual Builder displays the Visual Builder window, as shown in Figure 7. 

Starting Visual Builder from a WorkFrame Project folder 

You can start Visual Builder from a WorkFrame Project folder in the following ways. 

Note: The following steps assume that your project inherits the settings of a C Set 
++ project or that it was created using a Project Smarts template. 

• If the WorkFrame Project folder is closed, you can click on the folder with 
mouse button 2 and select Visual from the pop-up menu. 

• If the WorkFrame Project folder is open, you can do any one of the following: 

- Double-click on the name of the .vbb file 
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- Click on the name of the .vbb file with mouse button 2 and select Visual 
from the pop-up menu. 

- Click on the white space in the project folder with mouse button 2 and select 
Visual from the pop-up menu. 

Visual Builder displays the Visual Builder window, as shown in Figure 7 on 
page 27. If you double-clicked on a .vbb file to open Visual Builder, that file 
and all other .vbb files that you selected are preloaded. 

When you start Visual Builder from a WorkFrame Project folder, the menu bar in the 
Visual Builder window and in each of the Visual Builder editor windows contains an 
additional Project choice. Selecting this choice displays a list of the WorkFrame 
actions that are currently at the project scope for the project with which you are 
working. Examples of actions you might see in this list are Debug, MakeMake, 

Build, Run, Database, and Browse. 
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Part 2. Touring Visual Builder 

This part begins by introducing you the place where everything starts. Visual 
Builder’s Visual Builder window. It then provides an overview of the Visual Builder 
editors: the Composition Editor, the Class Editor, and the Part Interface Editor. 
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Getting Acquainted with 
the Visual Builder Window 


This chapter shows you how to set up a WorkFrame project to use Visual Builder, 
start Visual Builder, work with .vbb files, and use the functions available to you in 
the Visual Builder window. 


Getting to Know the Visual Builder Window 

The Visual Builder window is shown in Figure 8. 



Figure 8. Visual Builder Window 


This window contains the following areas: 

• The Loaded Part Files list box 

Parts that you create are stored in files with an extension of .vbb. These files are 
called part files. You can share part files that you create with other programmers 
so that they can reuse your parts. 

This list box shows all of the part files that are currently loaded. Visual Builder 
provides the following part files: 
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VBBase.vbb 

Contains the base parts that Visual Builder provides. This file is always 
loaded. 

VBMM.vbb 

Contains multimedia parts. 

VBSOM.vbe 

Contains Direct-to-SOM parts that you can use in Visual Builder. You must 
import this file to use the parts. 

VBCC.vbe 

Contains sample parts based on the IBM Collection Class Library. You must 
import this file to use the parts. 

VBSample.vbb 

Contains miscellaneous sample parts. 

O 

Part files must be loaded into Visual Builder for you to use the parts that they 
contain. Once part files are loaded, you can perform actions on them and on the 
parts that they contain by using the choices in the Visual Builder’s menu bar. 

O 


You can access the same choices that are available in the menu bar by 
moving the mouse pointer over a list box and pressing mouse button 2 to 
display a pop-up menu. Each pop-up menu contains only the menu choices 
that pertain to the contents of the list box over which it is displayed. The 
pop-up menu that Visual Builder displays for the Loaded Part Files list 
box, for example, contains only the menu choices that pertain to part files. 

Also, the pop-up menu for the Visual Parts list box only affects parts that 
are selected in that list box, even if parts are also selected in the Nonvisual 
Parts list box, and vice versa. For example, to simultaneously open both a 
visual and a nonvisual part, you must select Part—»Open from the menu 
bar. If you select Open from the pop-up menu for the Visual Parts list 
box, you can only open a visual part. The same is true for the pop-up 
menu for the Nonvisual Parts list box. 

The choices on the Part menu apply to selected items in all of the list 
boxes in the Visual Builder window. This includes the Loaded Type 
Information list box, which you display by selecting Options^Show type 
list. 


The .vbb files that Visual Builder provides are read-only files. Store the 
parts that you create in your own .vbb files. 


For more information about part files and the actions you can perform on them, 
see “Working with the Files for Storing Parts, .vbb Files” on page 33. 
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• The Visual Parts list box 

This list box displays the names of the visual parts that the selected part file 
contains. Visual parts are parts that the person using your application can see, 
such as frame windows, push buttons, and sliders. 

• The Nonvisual Parts list box 

This list box displays the names of the nonvisual parts and the class interface 
parts that the selected part file contains. Nonvisual parts are parts that your 
application uses to perform its functions, but the person using your application 
never sees them. For example, an object factory, which creates new instances of 
objects, is a nonvisual part. The user sees only the objects that the object factory 
creates, not the object factory itself. 

Class interface parts are nonvisual parts that have no notification ability. Thus, 
these parts cannot send events to other parts. You can use C++ classes that you 
have written as class interface parts in Visual Builder. 


Working with the Files for Storing Parts, .vbb Files 

The topics in this section describe how to perform various actions on part files from 
the Visual Builder window, shown in Figure 8 on page 31. 

Loading Part Files 

To give Visual Builder access to parts, you must load the contents of the part files 
that contain those parts by doing the following: 

1. Select File^-Load file in the Visual Builder window. 

Visual Builder displays the window shown in Figure 9. 


File - Load 


Open filename: 

*.VBB 

Type of file: 

Drive: 

<AII Files> 

V D: [PROGRAMS] sj 

File: 

Directory: 

Address.vbb 

J pQIBMCPP 

datetime.vbb 

■1 SDDE4VB 

KeysHelpTest.vbb 

□ FETest 

MainView.vbb 

□ FETest2 

MyFriends.vbb 

□ToDoList2 



OK 

Cancel 




Figure 9. File — Load Window 
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2. Select the file or files that you want to load. 

3. Select the OK push button. 

When you are just loading one file, it is quicker to double-click on the file 
name instead of selecting the file name and the OK push button. 


The file name or names are displayed in the Loaded Part Files list box in the 
Visual Builder window. Figure 10 shows the Visual Builder window with 
multiple .vbb files loaded. 



Figure 10. Visual Builder Window with Multiple .vbb Files Loaded 


For information about unloading files, see “Unloading Part Files.” 

Unloading Part Files 

If a part file appears in the Loaded Part Files list box in the Visual Builder window. 
Visual Builder has access to the parts that the part file contains. If you do not want 
Visual Builder to have access to those parts, you can unload the part file, with the 
exception of vbbase.vbb. To unload one or more part files, do the following: 

1. Select one or more files in the Loaded Part Files list box. 

To select multiple files, hold down the Ctrl key while clicking on a file name 
with mouse button 1. 

2. Select File^Unload file. 
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The following window is displayed showing the files you selected to unload: 


File - Unload 


D:\IBMCPP\DDE4VBWBSample.vbb 


Unload 


Cancel 


Help 


Figure 11. Unload Part Files Window 

At this point, you can review the files that you selected and make any changes by 
deselecting any file or files that you want to remain loaded. 

3. Select the Unload push button. 

The window disappears and the file names are removed from the Loaded Part 
Files list box. 

For information about loading files, see “Loading Part Files” on page 33. 

Selecting All Part Files 

To select all of the part files, select Edit—^Select all files. Visual Builder highlights 
all of the part files listed in the Loaded Part Files list box. 

At this point, you can review the list to see if you want to deselect any of the files. 

Deselecting All Part Files 

To deselect all of the part files, select Edit^Deselect all files. Visual Builder 
removes the highlighting from all of the selected part files listed in the Loaded Part 
Files list box. 

At this point, you can review the list to see if you want to select any of the files. 
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Customizing the Information Area 

The following options allow you to specify the kind of information that Visual 
Builder displays in the information area for a selected part in the Visual Builder 
window. To use these options, select Options—^Information area and then select 
one of the following options: 

Show base class 

Displays the C++ notation for a class and its base class. For example, if you select 
IVBContainerControl when this option is selected. Visual Builder displays the 
following in the information area to show that IControl is IVBContainerControl’s 
base class: 

IVBContainerControl::IControl 

Show description 

Displays a brief description of the selected part. For example, if you select 
IVBContainerControl when this option is selected. Visual Builder displays the 
following description in the information area: 

IBM container control, any view 

Show full file names 

Displays the name of the part file in which the part is stored. For example, if you 
select IVBContainerControl when this option is selected. Visual Builder displays 
the following file name in the information area to show that VBBase.vbb contains 
the IVBContainerControl part. 

VBBase.vbb 


Seeing the Base Files 

Select Options—»Show base files to see the names of the parts in the .vbb files that 
Visual Builder provides, as follows: 

VBBase.vbb 

Contains the base parts that Visual Builder provides. 

VBCC.vbb 

Contains sample parts based on the IBM Collection Class Library. 

VBMM.vbb 

Contains sample multimedia parts. 
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Seeing Where Part Files Are Located 

Select Options—s-Show full file names to see the drive and directory where each of 
your part files is stored. 


Seeing the Type List 

The type list shows the types of data, such as enumerations and typedefs, for the parts 
contained in the .vbb file that is currently selected. If no .vbb file is selected or if the 
selected .vbb file has no data types defined, this list is empty. 

Once a type list is displayed, you can perform the following functions on data types 
that are selected: 

• Delete data types 

• Move data types to another part file 

• Export data type definitions into part information files 

These functions are available in the Part pull-down menu. 

To display a type list, do the following: 

1. Select the part file or files for which you want to see defined types. 

2. Select Options-5-Show type list. 

A list box titled Loaded Type Information is displayed at the bottom of the 
Visual Builder window, as shown in Figure 12 on page 38. 
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Visual Builder - D:\IBMCPP\WORKING\ 


File Part Edit Options Help 
Loaded Part Files 


VBBase.vbb 


VBSAMPLE.VBB 


Visual Parts Nonvisual Parts 


lAnimatedButton 


lOString 


IBaseComboBox 


lAcceterator 


IBaseListBox 


lACollection 


IBaseSpinButton 


lAOrderedCollection 


IBitmapControl 


lApplication 


IButton 


lASequence 


iranva^ 

•v 

lASpni ipntlairnllprtinn 

V 

_| JJ 


> 



Loaded Type Information 

Boolean 

CHAR 


Figure 12. Visual Builder Window with Type List Displayed 


Using File Allocation Table (FAT) File Names 

Select Default to FAT file names if your system uses the File Allocation Table 
(FAT) file system instead of the High Performance File System (HPFS). This option 
is selected by default when you first install VisualAge C++. The FAT file system 
limits file names to a maximum of eight characters and file name extensions to a 
maximum of three characters. 

When you select this option. Visual Builder uses these limits when creating file 
names and extensions, such as in the Class Editor when it provides a file name and 
extension for you to use when generating default code. For example, suppose you 
create a part and name it MyNewPart. This name has nine characters. If you 
generate code for this part, the default file name that Visual Builder uses for the files 
it generates will have only eight characters, as will the .vbb file in which the part is 
saved if you allow Visual Builder to use a default name for that, too. 
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Be aware that Visual Builder does not check for existing file names when 
creating default file names. If you always use the default file name on a 
FAT system, Visual Builder may use a file name that has already been 
used, which may cause an existing file to be written over. For example, if 
you created another part named MyNewPart2, Visual Builder would use the 
same default file name as it used for MyNewPart. 

Visual Builder assigns the file name when you create the part. Deselecting 
the Default to FAT file names option does not change the name of a file 
that has already been created. 


Generating Make Files 

Select Generate make files if you want Visual Builder to generate a make file for 
you when you generate the default source code for the main() function of your 
application. 


Setting the Working Directory 

Select Options—»Set working directory if you want to store files created with Visual 
Builder in a different working directory. The default working directory is the 
directory in which you installed Visual Builder. 

When you select this option. Visual Builder displays the window shown in Figure 13: 



Figure 13. Window for Setting the Working Directory 


To change the working directory, do the following: 

1. Type the complete path to the directory in which you want to store Visual 
Builder files that you create. 

The path consists of all directories that must be opened to get to the working 
directory. 
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2. Select the OK push button. 

If the path you enter in the Working Directory window is invalid. Visual Builder 
displays an error message and resets the path to the last valid path that was entered. 


Refreshing the Display 

You might want to ensure that the information displayed in the Visual Builder 
window is current, for example, when you have loaded and unloaded several part files 
or moved parts from one part file to another. If such a situation occurs, you can 
cause the display to show the latest updates by selecting Edit^Refresh. 
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Getting to Know the Visual Builder Editors 


This chapter takes you on a tour of the Visual Builder editors. It begins with an 
overview of the editor symbols and then examines each editor in detail. 


The Editor Symbols 

The Editor symbols, located at the bottom-right corner of the window, provide a 
fast-path to each of the Visual Builder Editors. They are as follows: 



Composition Editor Use the Composition Editor to create the views for 
your application, choose the parts that perform the 
logic you need, and make connections between the 
parts. 

To leam more about the Composition Editor, see 
“The Composition Editor” on page 42. 



Class Editor 


Use the Class Editor to specify the names of files 
that Visual Builder writes to when you generate 
default code. You can also use this editor to do the 
following: 

• Enter a description of the part 

• Specify a different .vbb file in which to store 
the part 

• See the name of the part’s base class 

• Modify the part’s default constructor 

• Enter additional constructor and destructor code 

• Specify a .lib file for the part 

• Specify a resource DLL and ID to assign an 
icon to the part 

• Specify other files that you want to include 
when you build your application 


© Copyright IBM Corp. 1992, 1995 


To leam more about the Class Editor, see “The 
Class Editor” on page 51. 
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Part Interface Editor 

You can use the Part Interface Editor to define the 
features (attributes, actions, and events) for your 
parts, along with a list of preferred features for the 
pop-up connections menu. These features make up 
the part’s interface. You use them when you make 
connections between collaborating parts. You can 
also promote features of subparts from this editor. 

To learn more about the Part Interface Editor, see 
“The Part Interface Editor” on page 57. 


The Composition Editor 

The heart of Visual Builder is the Composition Editor. Use the Composition Editor 
to lay out the visual parts that make up your views, choose the parts that perform the 
logic you need, and make connections between them. 

The Composition Editor is the editor you use to visually compose the various parts of 
your application. This section provides an overview of the Composition Editor's 
components. See Chapter 8, “Learning to Use Parts” on page 115 for information 
about visually composing an application. 

The Composition Editor is shown in Figure 14 on page 43. 
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o 

Tool bar 

o 

Connection lines 

© 

Fferts palette - Categories 

© 

Free-form surface 

o 

ferts palette - Parts 

o 

Information area 



o 

Editor symbols 


Figure 14. The Composition Editor 


The Tool Bar 

The tool bar appears below the menu bar of the Composition Editor. It contains 
icons that provide convenient access to actions that you commonly use when you 
create composite parts. These tools help you perform such tasks as: 

• Aligning parts within your composite part 

• Managing the connections between parts 

• Unloading the mouse pointer. 

• Generating code for the part you are editing 
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All of the tools in the tool bar, except the Selection tool, act on the selected objects. 

All of the tools available from the tool bar are also available from the Tools 
menu found on the Composition Editor’s menu bar, except for the tool used 
to generate source code for your part. This tool is available in the File 
menu as the Save and generate^-Part source choice. 


The tool bar contains the following tools: 




Part Code Generation 

Generates C++ source code for the part that you are 
currently editing. This tool performs the same 
function as the File-*Save and generate^-Part 
source menu choice. For information about the 
source code files that Visual Builder generates, see 
“Source Files Created during Part Code Generation” 
on page 273. 


Selection tool Changes the mouse pointer from the crosshairs, 

which are used when the mouse pointer is loaded 
with a part, to the arrow that is used to select parts 
and perform actions on them. If the mouse pointer 
is not loaded, this tool is not available. 


Connection tools 


§ 


Show Connections Displays all hidden connections to or from the 
selected parts. If no parts are selected, all 
connections are shown. 


Hide Connections Hides all displayed connections to or from the 
selected parts. If no parts are selected, all 
connections are hidden. 
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Grid tools 


Toggle Grid 


Toggles the display of the part alignment grid on 
and off for the selected parts. You can use separate 
alignment grids for parts in the Composers category 
and for the free-form surface. 



Snap To Grid 


Causes the selected parts to be repositioned to the 
nearest grid coordinate. The grid does not need to 
be visible for Snap To Grid to work. 


Select the Snap On Drop and Snap On Size choices found in the 
Composition Editor Options menu to automatically align to the grid all 
parts that you add or size. This allows you to align parts to the grid 
without having to select the Snap To Grid tool for each part. Use the Snap 
To Grid tool if you only want to align selected parts to the grid. 


Alignment tools 


n 


Align Left 



Align Center 


□; 
l*X*l I 


Align Right 



Align Top 


Aligns the selected parts to the left edge of the last 
part selected. 


Aligns the selected parts along the vertical axis of 
the last part selected. 


Aligns the selected parts to the right edge of the 
last part selected. 


Aligns the selected parts to the top edge of the last 
part selected. 


1 



Align Middle 


Aligns the selected parts along the horizontal axis 
of the last part selected. 
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.... Align Bottom Aligns the selected parts to the bottom edge of the 

last part selected. 


Distribution tools 



Distribute Horizontally 

Spaces the selected parts evenly between the left 
and right window borders. 



Distribute Vertically 

Spaces the selected parts evenly between the top 
and bottom window borders. 


For information about the horizontal and vertical 
distribution of visual parts within a bounding box, 
see “Spacing Parts Within a Bounding Box” on 
page 140. 


Sizing tools 


Match Width 


Sizes the width of the selected parts to match that 
of the last part selected. 



Match Height 


Sizes the height of the selected parts to match that 
of the last part selected. 


The Parts Palette 

The parts palette is found on the left side of the Composition Editor. It contains 
icons for the parts that you use most frequently. 

The parts palette organizes parts into categories. The icons in the left column of the 
parts palette represent the part categories. The right column of the parts palette 
contains the parts you use to build your application. When you select a category in 
the left column, the right column shows the parts contained within that category. 
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Notes: 

• The information area at the bottom of the Composition Editor indicates which 
category and part are currently selected on the palette or which part or connection 
is currently selected on the free-form surface. 

• You can add categories and parts to the parts palette, as well as delete categories 
and parts from it. See Chapter 18, “Adding Categories and Parts to the Parts 
Palette” on page 285 for information about adding parts that you create to the 
parts palette. 

• See “Working with Parts on the Free-form Surface” on page 127 for information 
about putting parts on the free-form surface. 

The Visual Builder parts palette contains the following categories and parts. Refer to 
the Visual Builder Parts Reference for descriptions of these parts. 




Data entry 


Contains the following button parts: 

I IPushButton* 

©IRadioButton* 


7 


ICheckBox* 

INumericSpinButton* 
ITextSpinButton* 


© 



IGraphicPushButton* 


IAnimatedButton* 


Contains the following data entry parts: 



IStaticText* 

IEntryField* 



< 1 I >| I IMultiLineEdit* 
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IGroupBox* 


IOutlineBox* 


IBitmapControl* 


IlconControl* 


Lists 


Contains the following list parts: 


~cEc 


IListBox* 


ICollectionViewListBox* 


finEc 


IComboBox* 


ICollectionViewComboBox* 


□ 



IVBContainerControl* 


IContainerColumn* 


Frame Extensions Contains the following parts that you can add to a 
window frame: 


I I I I I IToolBar* 

I I I I I IToolBarButton* 

[ 


IMenu* 
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Sliders 



Composers 




IMenuItem* 


4 1 

: ; IMenuCascade* 



IMenuSeparator* 

IlnfoArea* 


T:tk 


' ITitle* 


Consists of the following slider parts: 

... 

I I IProgressIndicator* 

Hill MH ISlider* 

\<\ |>| IScrollBar* 


Consists of the following parts that are used to 
contain other visual parts: 

IMultiCellCanvas* 

ISetCanvas* 

ISplitCanvas* 

|<| | >| IViewPort* 

n 

INotebook* 



ICanvas* 


IFrameWindow* 
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Contains the following nonvisual parts to help 
implement the logic of your application: 



IVSequence* 

the following miscellaneous parts: 

IHelpWindow* 

IMessageBox* 

IVBFileDialog* 

IVBFontDialog* 

IVBFlyText* 

The Free-form Surface 

The large open area in the Composition Editor is called the free-form surface. This is 
the working area for visual programming, where you compose the various visual parts 
of your application and where you make connections to the logic of your application. 

You add visual parts, such as static text and push buttons, to either a frame window 
part, to another part from the Composers category, or to the free-form surface itself. 
You add nonvisual parts, such as object factories, and class interface parts to your 
application by placing them on the free-form surface, not on a frame window part or 
on any other part from the Composers category. 

For more information about using the free-form surface, see “Working with Parts on 
the Free-form Surface” on page 127. 
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The Class Editor 

The Class Editor is the editor you use to specify the names of files that Visual 
Builder writes to when you generate default code. You can also use this editor to do 
the following: 

• Enter a description of the part 

• Specify a different .vbb file in which to store the part 

• See the name of the part’s base class 

• Modify the part’s default constructor 

• Enter additional constructor and destructor code 

• Specify a .lib file for the part 

• Specify a resource DLL and ID to assign an icon to the part 

• Specify other files that you want to include when you build your application 

Use your favorite text editor for creating new classes and member functions, writing 
application logic, and modifying existing member functions. 

The Class Editor is shown in Figure 15 on page 52. 
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Figure 15. The Class Editor 

If you cannot see all of the fields shown in the preceding figure, use the scroll bar on 
the right side of the Class Editor to see the remaining fields. 

Entering a Description of a Part 

The Description field in the Class Editor is an entry field in which you can enter a 
description of your part. This description is used in the following places: 

• If you add your part to the parts palette, the description appears in the 
information area at the bottom of the Composition Editor when you select the 
part. 

• If you export your part information into a .vbe file, the description is included in 
the first line. 

In the following example, the text shown in quotation marks was taken from the 
Description field for the ToDoList part. 

//VBBeginPartlnfo: ToDoList,"To-Do List sample application" 
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Moving a Part to a Different .vbb File 

The Part file specification field in the Class Editor shows the name of the .vbb file 
that contains this part. If you want to move this part to another .vbb file while using 
the Class Editor, do the following: 

1. Replace the name of the current .vbb file with the name of another .vbb file in 
which you want to store the part. 

2. Select File-^Save to apply the change. 

Visual Builder moves the part from the former .vbb file to the one you just 
specified. If the .vbb file you specified does not exist. Visual Builder creates it 
for you. 

Seeing the Base Class of a Part 

The Base class — access level field in the Class Editor shows the name of the base 
class for your part. This is the class name that you specified as the base class when 
you created the part. 

This field also shows you the current access level to the base class: public, protected, 
or private. 

You cannot modify the base class name or the access level. 

Modifying a Part’s Constructor 

The Constructor field in the Class Editor initially contains a default constructor that 
Visual Builder inserts for you. If the default constructor does not do exactly what 
you want it to do, you can modify it by typing over the text in this field. 

If you want your class to have multiple constructors, we recommend putting them in 
the .hpv and .cpv files that contain your default feature code and then including them 
when you generate your code. Otherwise, if you modify your code after generating 
it, your changes will be lost the next time you generate your code. 

For information about including files, see “Specifying Files to Include When You 
Build Your Application” on page 56. 
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Specifying Your Own Constructor Code 

Use the User constructor code field in the Class Editor to enter your own 
constructor code for the part that you are editing. If you enter code in this field, it is 
added at the end of the default constructor that Visual Builder provides for you. If 
you have more than one line of code, put your code into a function and put the 
function name in this field. Put the code for this function in the files that Visual 
Builder creates when you generate your default feature code. These file names are 
specified in the User .hpv file and User .cpv file fields. 

Specifying Your Own Destructor Code 

Use the User destructor code field in the Class Editor to enter your own destructor 
code for the part that you are editing. If you enter code in this field, it is added at 
the beginning of the default destructor that Visual Builder provides for you. If you 
have more than one line of code, put your code into a function and put the function 
name in this field. Put the code for this function in the files that Visual Builder 
creates when you generate your default feature code. These file names are specified 
in the User .hpv file and User .cpv file fields. 

Specifying a Library File 

Use the .LIB file name field in the Class Editor to specify the name of a library file 
(partname. lib) that you want to to be included when you generate the source code for 
your part. The library file points to a .dll file that contains information about a 
subpart in your application that was compiled separately. When you generate the 
source code for your part. Visual Builder includes a #pragma statement to include the 
library file. 

When Visual Builder generates make files for other parts that use this part, the .lib 
file is specified in the make file as a dependency. 

Specifying a Starting Resource ID 

Use the Starting resource id field in the Class Editor to specify the number that 
Visual Builder is to use as a starting point for generating resource IDs for your part. 
The resource IDs that Visual Builder generates are written into a file named 
partname. h, which Visual Builder creates when you generate code for your part. 

The check box next to the field enables the starting resource ID. The first time you 
select this check box. Visual Builder inserts a default starting resource ID. You can 
change this number. 

If you deselect the check box, the field is disabled. The number in the field is 
included in the partname .h file when you generate your code, but it is not referenced. 
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Generating resource IDs is useful if the text in your application is being translated 
into another language. See Chapter 19, “Enabling National Language Support for an 
Application” on page 293 for more information about using starting resource IDs. 

Specifying a Unique Icon for Your Part 

Fill in the fields in the Icon group box in the Class Editor before you add your part 
to the parts palette so that you can use an icon other than the default icon provided 

by Visual Builder to represent your part. The default icon is 

The Icon group box contains the following fields: 

DLL name 

An entry field in which you enter the name of the resource DLL that contains the 
icon you want to use. Enter just the file name, not the extension. 

Resource Id 

The resource ID number of the icon in the DLL whose name you entered in the 
DLL name field. 

When you enter both the DLL name and a valid resource ID number. Visual Builder 
displays the icon that matches the resource ID number in the area below the 
Resource Id field. This occurs when you click on another field. This allows you to 
verify that you entered the correct resource ID number. 

Specifying the Names of Your Code Generation Files 

The Code generation files group box in the Class Editor contains the following 
fields: 

• A C++ header file (.hpp) field 

• A C++ code file (.cpp) field 

The file names displayed in these fields are the files into which your C++ header file 
code and source code are written. This occurs when you generate default code from 
the Visual Builder window or from any of the editors by selecting File^Save and 
Generate^Part source. 

For complete information about generating default source code, see Chapter 16, 
“Generating Source Code for Parts and Applications” on page 271. 

The fields in the group box initially contain .hpp and .cpp file names that are based 
on the name of the part you are editing. To change the file names in these fields, 
select File^-Save so that Visual Builder uses the new file names. 
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Warning: If the files already exist. Visual Builder replaces their contents with the 
code currently being generated. 

Visual Builder writes both files to the current directory. 

Specifying Files to Include When You Build Your Application 

The User files included in generation group box in the Class Editor allows you to 
specify files that you want to be included when you build your application. These 
fields are typically used to contain the names of the files that hold user code that 
Visual Builder is to use when you generate default feature code for your part’s 
features. 

The .hpv and .cpv file extensions are used because the WorkFrame Build tool tries to 
compile every .cpp file that it finds into an object module (.obj file). Since these files 
are not meant to be compiled by themselves, we selected a different file extension for 
you to use to prevent this from happening. 

The group box contains the following fields: 

User .hpv file 

Use this field to enter the name of a header file that you want to be included in the 
header file that Visual Builder generates. You must enter a file name in this field 
before you can generate default feature code. 

User .cpv file 

Use this field to enter the name of a code file that you want to be included in the 
source code file that Visual Builder generates. You must enter a file name in this 
field before you can generate default feature code. 

User .h file 

Use this field to enter the name of a resource header file that contains resource IDs 
for your application other than those that Visual Builder generates for you in the 
partname .h file. This file is included in partname. h. 

User .rev file 

Use this field to enter the name of a resource file that contains text strings used in 
your application other than those that Visual Builder generates for you in the 
partnamesc file. This file is included in partname. re. 

The .rev file extension is used because the WorkFrame Build tool tries to compile 
every .re file that it finds into a binary resource (.res) file. Since partial resource 
files cannot always be compiled by themselves, we selected a different file 
extension for you to use to prevent this from happening. 

Required include files 

This field is a multiline entry field in which you can enter the names of other files 
that you want Visual Builder to include when you generate default source code for 


56 


Visual Builder User’s Guide 



Touring Visual Builder 


your application. Some examples of files that you might want to include are the 
following: 

• Standard C++ library files, such as streamio.h 

• IBM Open Class Library header files, such as IString.hpp 

Visual Builder generates the #i ncl ude statements in the default source code. 

If you type a label next to the file name. Visual Builder uses that label to generate 
lifndef and #endif statements for you. For example, if you want to include the 
header file for an address part that you created, you might enter the following in 

the Additional Include Files field: 

address.hpp _ADDRESS_ 

This would cause Visual Builder to generate the following in your default .cpp 
source code file: 

lifndef _ADDRESS_ 

#include <address.hpp> 
lendif 

If you omit the label. Visual Builder generates only the #i ncl ude statement. 


The Part Interface Editor 

Each part that Visual Builder provides has a defined part interface that allows the 
part to interact with other parts. The part interface consists of features —attributes, 
events, and actions—that allow you to use the part in constructing your application. 
An entry field, for example, has a text attribute, a push button has a buttonClickEvent 
feature, and a frame window has a setFocus action. 

The parts that you create must also have a defined part interface so they can be used. 
Use the Part Interface Editor to define that interface. To learn more about building 
reusable parts, see Chapter 7, “Creating Nonvisual Parts” on page 101. 

Other uses for the Part Interface Editor include the following: 

• Viewing the interface of a part 

• Modifying or extending the interface of an existing part 

• Creating or altering the list of preferred features, the features that are displayed 
in the pop-up connection menu for a part 

The Part Interface Editor is a notebook made up of the following visual components: 

• The Attribute page 

• The Event page 

• The Action page 

• The Promote page 
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• The Preferred page 

The Attribute Page 

Use the Attribute page of the Part Interface Editor, shown in the following figure, to 
define the attributes for your part. 


S OAContract - Part Interface Editor 
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Figure 16. The Attribute Page of the Part Interface Editor 


You can define many attributes for a part, each with unique characteristics, such as 
name and data type. An attribute’s value is always acquired by using the attribute’s 
get and set member functions. It is up to you whether data for the attribute is stored 
in a data member, calculated, or acquired from some other location. 

In addition, you can define three different kinds of behavior for your attributes, as 
follows: 

full attribute 

A full attribute contains all of the characteristics and behaviors that are available 
for an attribute, as follows: 
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• A get member function, which is required 

• A set member function, which is optional (see no-set attribute below) 

• An event identifier, which is optional (see no-event attribute below) 

no-set attribute 

A no-set attribute has no set member function. It can initialize another attribute if 
it is the source of an attribute-to-attribute connection, but it cannot set itself to the 
value of another attribute. 

no-event attribute 

A no-event attribute has no event identifier. Therefore, if you use a no-event 
attribute as the source of a connection, it cannot signal another part because of the 
lack of an event identifier. However, you can still use it as the source of 
connections so that it can initialize other attributes. 

Adding an Attribute 

To add an attribute in the Part Interface Editor, do one of the following: 

• If you want to add the attribute using the default attribute type, get member 
function, set member function, and event identification that Visual Builder 
provides, enter a name in the Attribute name field and select the Add with 
defaults push button. 

Visual Builder adds the attribute to the part interface. 

• If you want to see the default attribute type, get member function, set member 
function, and event identification that Visual Builder provides before you add the 
attribute, select the Defaults push button. 

Visual Builder displays the default information for the attribute in the fields on 
the right side of the Attribute page. Here are descriptions of those fields: 

Attribute name 

The name of the attribute. This name appears in the connection menu for the 
part when you make connections to or from it in the Composition Editor. 

Attribute type 

The data type of the attribute. The first time you create an attribute for your 
part, the default data type that Visual Builder uses is IStandardNotifier. If you 
change IStandardNotifier to another data type, such as IString, the new data 
type becomes the default data type for any new attributes that you create until 
you change it to something else or close the Part Interface Editor window. 
When you reopen the Part Interface Editor window, the default data type for 
any new attributes that you create reverts to IStandardNotifier. It stays that 
way unless you change it again when creating another attribute or when 
modifying an existing attribute. 
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You typically define attributes as private data members to protect them from 
being changed by users of the part. The get and set member functions that you 
define for an attribute give other programmers access to the attribute’s value. 
You probably do not want to expose all of the data members of your part as 
attributes, particularly if you intend to share the part with other programmers. 
You only need to decide which of the data members you want to make 
available for other programmers to reference. Some of your data members 
might be used for implementation purposes, so you would not want to identify 
these as attributes. 

Get member function 

The public member function used by the part and other parts to query or get 
the value of the attribute. 

Set member function 

The public member function used by the part and other parts to set the value of 
the attribute. An event identifier is typically signalled from within the 
implementation of the set member function to indicate that the value of the 
attribute changed. 

If you press either the Defaults or Add with defaults push button. Visual 
Builder uses the data type in the Attribute type field to determine whether the 
parameter on the set member function passes the actual value of the attribute 
being set or simply references the location of that value, as follows: 

- If the data type in the Attribute type field represents the class name of a 
part in a loaded .vbb file. Visual Builder references the location of the 
value that is to be used to set the attribute. 

For example, suppose you create a part named MyPart. If you create a 
text attribute for MyPart with a data type of IString and select either 
Defaults or Add with defaults. Visual Builder puts the following in the 

Set member function field: 

MyPart & setText(const IString &aText) 

The & in front of the aText parameter means that, unless you modify this 
member function, it passes a reference to the value being used to set the 
text attribute. The & is used because IString is defined as a part in 
vbbase.vbb. 

- If the data type in the Attribute type field is not defined in any loaded 
.vbb file, or if it is defined in a .vbb file but it does not represent the class 
name of a part. Visual Builder passes the actual value that is to be set for 
the attribute. 

Using the MyPart example again, if you put an undefined data type in the 
Attribute type field before selecting either Defaults or Add with 
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defaults. Visual Builder puts the following in the Set member function 
field: 

MyPart & setText(const myType aText) 

In this example, unless you modify this member function, it passes the 
actual value being used to set the text attribute. 

Event identification 

The name of the event identifier that is typically signalled from within the 
implementation of the set member function. You can create one of your own 
or you can use the default event identifier that Visual Builder supplies when 
you select either Defaults or Add with defaults. 

Use this identifier to notify this part and other parts that the attribute’s value 
has changed. This is typically done when the attribute is used as the source of 
a connection. The connection types that use an attribute as the source of a 
connection are: 

- Attribute-to-attribute 

- Attribute-to-action 

- Attribute-to-member function 

- Custom logic, which can use either an attribute or an event as the source 
of a connection 

You are not required to specify an event identification for any attribute because 
you are not required to notify other parts when the value of the attribute 
changes. However, failing to do so could prevent your application from 
passing necessary information from one part to another when it is needed. 

The event identifier is typically signalled from within the implementation of 
the attribute’s set member function, causing the attribute to behave as an event. 
Therefore, you do not need to specify another event with this event identifier 
on the Event page of the Part Interface Editor. 

Description 

A description of the attribute. This entry field is blank unless you enter a 
description, or you select either the Defaults or Add with defaults push 
button, in which case Visual Builder supplies a default description consisting 
of the attribute’s name. 

If you want to add the attribute after seeing or modifying its default information 
or after entering your own information, select the Add push button. 

Visual Builder adds the attribute to the part interface. 
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Changing an Attribute 

To change, or update, an attribute in the Part Interface Editor, do the following. 

Note: You can change anything about an attribute except its name. To change an 
attribute’s name, you must create a new attribute with the name you want to 
use. 

1. Select the attribute that you want to change or type its name in the Attribute 
name field. 

2. Make the changes that you want to make in the fields on the right side of the 
Attribute page. 

3. Select the Update push button. 

Visual Builder saves the changes you made. 

Deleting an Attribute 

To delete an attribute in the Part Interface Editor, do the following: 

1. Select the attribute that you want to delete or type its name in the Attribute 
name field. 

2. Select the Delete push button. 

Visual Builder deletes the attribute. 

Note: If you added the attribute that you just deleted to the preferred features 
list, you must go to the Preferred page and delete it there, too. 

Setting Defaults for an Attribute 

To set defaults for an attribute in the Part Interface Editor, do the following: 

1. Select the attribute that you want to set defaults for or type its name in the 

Attribute name field. 

2. Change the attribute type in the Attribute type field. 

3. Select the Defaults push button. 

Visual Builder changes all occurrences of the former attribute type to the new 
attribute type in the fields on the right side of the Attribute page. 


62 


Visual Builder User’s Guide 



Touring Visual Builder 


Clearing the Attribute Page Fields 

To clear the fields on the Attribute page, select the Clear push button. 

Visual Builder clears all of the fields on the Attribute page. 

An Attribute Example 

Suppose you create a nonvisual Customer part that inherits from Visual Builder’s 
sample ICustomer part. You also create an age attribute for which you specify the 
following: 

• An attribute type of IString 

• An age get member function 

• A setAge set member function 

• An ageld event notifier 

You create this attribute so other parts can access its value or so it can be passed as a 
parameter value. 

Note: Visual Builder does not use the value that is passed on the attribute’s event. 

It uses the attribute’s get member function instead. 


The default feature code that Visual Builder would generate for the age attribute 
would be similar to these code segments, which show the following: 

• The declarations of the get member function, set member function, event 
identifier, and data member in the user header (.hpv) file. 

public: 


IString age() const; 

Customer & setAge( 

/* 

Get member function 

*/ 

const IString &aAge); 

/* 

Set member function 

*/ 

static INotificationld ageld; 

/* 

Event notifier 

*/ 

private: 

IString iAge; 

/* 

Data member 

*/ 


• The event notifier initialized as a text string, followed by the get and set member 
functions for the age attribute, as defined in the user source code (.cpv) file. 

INotificationld Customer::ageld = "Customer::ageld"; 


IString Customer::age() const 

{ 

return iAge; 

} 

Customer & Customer::setAge( 

const IString & aAge) 

{ 


/* The age attribute's get */ 
/* member function returns */ 
/* the value of the data */ 
/* member. */ 

/* The age attribute's set */ 
/* member function sends */ 
/* the event notification */ 
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if (iAge != aAge) /* when the text changes. */ 

{ 

iAge = aAge; 

IString eventData(iAge); 

noti fyObservers(IN o tificationEvent(Customer:rage Id, *this, 
true, (void *)&eventData)); 

} /* endif */ 
return *this; 

} 


The Event Page 

Use the Event page of the Part Interface Editor, shown in the following figure, to 
define the events you use to notify this part or other parts about changes you decide 
are significant. For example, you might notify other parts when an attribute is set to 
a certain value or when important processing is finished. In this way, someone using 
your reusable part can link to one of your part's events and receive automatic 
notification of the event whenever it is triggered. 


OAContract - Part Interface Editor 


File Edit View Help 


□ 



Figure 17. The Event Page of the Part Interface Editor 
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If you cannot see all of the fields shown in the preceding figure, use the scroll bar on 
the right side of the Part Interface Editor to see the remaining fields. 

The names of the part’s events are displayed in the list box named Event name. 

When you create a new part, the first time you open the Part Interface Editor and turn 
to the Event page, you see that Visual Builder has provided an event for you: the 
ready event. 

The Ready Event 

Visual Builder adds the ready event to every new part that you create using the 
Part-^New menu choice in the Visual Builder window. However, this event is not 
added if you import part information from a part information file (.vbe file). 

By connecting the ready event to one of your part’s subparts, you can cause an action 
or member function to be invoked when your application is executed. The ready 
event is sent to the part when both of the following occur: 

• All subparts of the part have been constructed. 

• All connections have been made and initialized. 

For example, suppose you have a part named MyApp and this part is an application 
that has a window that contains an animated push button. By connecting the MyApp 
part’s ready event to the animated push button’s startAnimation action, you cause the 
push button to become animated as soon as the application starts running. 

The ready event is not a preferred feature by default, but you can add it to your part’s 
preferred features list. For information on how to do this, see “The Preferred Page” 
on page 75. 

Adding an Event 

To add an event in the Part Interface Editor, do one of the following: 

• If you want to add the event using the default event identification that Visual 
Builder provides, enter a name in the Event name field and select the Add with 
defaults push button. 

Visual Builder adds the event to the part interface. 

• If you want to see the default event identification that Visual Builder provides 
before you add the event, select the Defaults push button. 

Visual Builder displays the default event identification in the Event 
identification field on the right side of the Event page. Here are descriptions of 
that field and the other fields on the page: 
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Event name 

The name of the event. This name appears in the pop-up menu for the part 
when you make connections to or from it in the Composition Editor if you add 
it to the preferred features list. 

Event identification 

The name of the event identifier that is actually used in a member function 
signalling this event. 

Description 

A description of the event. This entry field is blank unless you enter a 
description or unless you select either the Defaults or Add with defaults push 
button. In the latter case. Visual Builder inserts a default description 
consisting of the event’s name. 

Parameters and their types 

A table used to define a parameter and data type sent as part of an event. 

Name The name of the event parameter. 

Type The class, or data type, of the event parameter, such as IString, 
integer, or unsigned long. 

The parameter that you specify in this table is used to specify event data, or a 
reference to that data's location, that you want to send along with the event 
identifier as part of the event. Doing this prevents you from having to perform 
a separate query for the data. 

To add a parameter and its type to this table, do the following. 

Note: You can add only one parameter and type for each event. 

1. Move the mouse pointer over the table and click mouse button 2. 

Visual Builder displays a pop-up menu. 

2. Select either Add before or Add after. 

Visual Builder adds a row to the table with a default parameter name and type. 

3. If you want to change the defaults, do the following: 

a. Click on the parameter name with mouse button 1. 

b. Type the parameter name you want to use. 

c. Click on the parameter type with mouse button 1. 

d. Type the parameter type you want to use. 

e. Select the Update push button. 
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Changing an Event 

To change, or update, an event, do the following. 

Note: You can change anything about an event except its name. To change an 

event’s name, you must create a new event with the name you want to use. 

1. Select the event that you want to change or type its name in the Event name 
field. 

2. Make the changes that you want to make in the fields on the right side of the 
Event page. 

3. Select the Update push button. 

Visual Builder saves the changes you made. 

Deleting an Event 

To delete an event, do the following: 

1. Select the event that you want to delete or type its name in the Event name 
field. 

2. Select the Delete push button. 

Visual Builder deletes the event. 

Note: If you added the event that you just deleted to the preferred features list, 
you must go to the Preferred page and delete it there, too. 

Setting Defaults for an Event 

To set defaults for an event, do the following: 

1. Select the event that you want to set defaults for or type its name in the Event 
name field. 

2. Select the Defaults push button. 

Visual Builder changes the former event identification to the default event 
identification in the Event identification field. 

Clearing the Event Page Fields 

To clear the fields on the Event page, select the Clear push button. 

Visual Builder clears all of the fields on the Event page. 
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An Event Example 

Using the same example shown for the Attribute page, suppose you also create an 
invalidDataEntered event for which you specify the following: 

• An invalidDataEnteredld event notifier 

• An invalidData parameter with a data type of IString 

You create this event because you want to show an error message for the Customer 
part whenever invalid data is entered for any of the Customer part’s attributes, such 
as the customer’s age being outside a valid range. Then, in your source code for the 
age attribute’s set member function, you can call the notifyObservers member 
function to display a message asking for a valid age if the check fails. 


The default feature code that Visual Builder would generate for the 
invalidDataEnteredld event notifier would be similar to these code segments, which 
show the following: 

• The declarations of the get member function, set member function, event 
identifiers, and data member in the user header (.hpv) file. 

Note: Sample code highlighted in bold shows the code that was added to 
modify the previous example. 

public: 

IString age() const; /* Get member function */ 

Customer & setAge( 

const IString &aAge); /* Set member function */ 

static INotificationld ageld; /* Event notitiers */ 

static INotificationld invalidDataEnteredld; 


private: 

IString iAge; /* Data member */ 

• The event notifier initialized as a text string, followed by the get and set member 
functions for the age attribute, as defined in the user source code (.cpv) file. 

INotificationld Customer::ageld = "Customer::ageld"; 

INotificationld Customer::invalidDataEnteredld = 

"Customer::invalidDataEnteredld"; 


IString Customer::age() const 

{ 

return iAge; 

} 

Customer & Customer::setAge( 
const IString &aAge) 

{ 

if (aAge > 99) 

{ 


/* The age attribute's get */ 
/* member function returns */ 
/* the value of the data */ 
/* member. */ 

/* The age attribute's set */ 
/* member function sends */ 
/* the event notification */ 
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notifyObservers( 

INotificationEvent( 

Customer::invalidDataEnteredld, 

*this, 

true, 

(void *) IString("Enter a value between 1 and 99."))); 

} 

else 

{ 

if (iAge != aAge) 

{ 

iAge = aAge; 

IString eventData(iAge); 

notifyObservers(INotificationEvent(Customer::ageld, *this, 
true, (void *)&eventData)); 

} /* endif */ 

} 

return *this; 


The Action Page 

Use the Action page of the Part Interface Editor, shown in the following figure, to 
define the actions your reusable part uses to perform specific tasks. Often, you will 
want to perform some task when a specific event occurs. 

For example, you might want to update a balance attribute each time a push button's 
buttonClickEvent feature is triggered. You might create an action named 
updateBalance to perform this task and connect it to the push button’s 
buttonClickEvent feature. 
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OAContract - Part Interface Editor 
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Figure 18. The Action Page of the Part Interface Editor 

The names of the part’s actions are displayed in the list box below the Action name 
field. 

Adding an Action 

To add an action in the Part Interface Editor, do one of the following: 

• If you want to add the action using the part you are editing as the default return 
type, enter a name in the Action name field and select the Add with defaults 
push button. 

Visual Builder adds the action to the part interface. 

• If you want to see the default return type before you add the action, select the 
Defaults push button. 

Visual Builder displays the default return type in the Return type field, as well 
as in the Action member function field, on the right side of the Action page. 
Here are descriptions of those fields and the other fields on the page: 
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Action name 

The name of the action. This name appears in the pop-up menu for the part 
when you make connections to or from it in the Composition Editor if you add 
it to the preferred features list. 

Action member function 

The name of the public member function, defined within your reusable part, 
that performs the action. 

Return type 

The return type of the action member function. 

Description 

A description of the action. 

Parameter Names 

Parameters of the selected action. Initially, the names that are inserted in the 
Parameter Names table are the same as the parameter names that are 
specified in the Action member function field. 

The parameter names in the table are linked to the action name and can appear 
in a pop-up connection menu. The purpose of the table is to allow you to 
change the parameter names that appear in the part interface without affecting 
the member function definition itself. That is, if you change the parameter 
names in the table, the parameter names in the Action member function field 
do not change. 

Here are some reasons for using the Parameter Names table: 

- To give parameters descriptive names. 

You can give parameters that appear in pop-up connection menus names 
that are more descriptive than those in the member function definition. 

- To associate specific parameter names with actions. 

You might have more than one action name for the same public member 
function. If so, to make your part interface easier to use, you might not 
want to have the same parameter name associated with each action. The 
Parameter Names table allows you associate separate, descriptive 
parameter names with each action, even though those names represent the 
same parameter in the same member function. 

- To change a member function without changing its action name in the part 
interface. 

You might decide to change a member function. For example, you might 
rename a parameter or substitute another member function entirely. The 
Parameter Names table allows you to do this without having to change 
your part interface. You can modify and then update the information in 
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the Action member function field without changing the parameter names 
in the table. Therefore, if other programmers are using your part, they 
continue to see the same part interface. They would only need to 
regenerate their source code. 


Changing an Action 

To change, or update, an action in the Part Interface Editor, do the following. 

Note: You can change anything about an action except its name. To change an 

action’s name, you must create a new action with the name you want to use. 

1. Select the action that you want to change or type its name in the Action name 
field. 

2. Make the changes that you want to make in the fields on the right side of the 
Action page. 

3. Select the Update push button. 

Visual Builder saves the changes you made. 


Deleting an Action 

To delete an action in the Part Interface Editor, do the following: 

1. Select the action that you want to delete or type its name in the Action name 
field. 

2. Select the Delete push button. 

Visual Builder deletes the action. 

Note: If you added the action that you just deleted to the preferred features list, 
you must go to the Preferred page and delete it there, too. 

Setting Defaults for an Action 

To set defaults for an action in the Part Interface Editor, do the following: 

1. Select the action that you want to set defaults for or type its name in the Action 
name field. 

2. Select the Defaults push button. 

Visual Builder changes the former return type to the default return type in both 

the Action member function and the Return type fields. 
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Clearing the Action Page Fields 

To clear the fields on the Action page, select the Clear push button. 

Visual Builder clears all of the fields on the Action page. 

The Promote Page 

Use the Promote page of the Part Interface Editor to specify features that you want 
to connect to another part when this part is embedded as a subpart within another 
part. The features (attributes, events, and actions) that you specify appear in the 
window that is displayed when you select More from this part’s pop-up connection 
menu. For a complete description of promoting a part’s features, see “Promoting a 
Part’s Features” on page 155. 

Figure 19 shows the Promote page: 


File Edit View Help 


Promote feature name 


Subpart name 


Feature type 


Promotable feature 


Add with defaults j Add Update Delete Defaults Clear 


Attribute Event Action 


Promote Preferred! 
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Figure 19. The Promote Page of the Part Interface Editor 
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Promoting a Feature 

To promote a feature in the Part Interface Editor for a subpart, do the following: 

1. Select a subpart name from the list box beneath the Subpart name field or type 
the name in the field. 

Visual Builder displays the name of the subpart that you select in the Subpart 
name field. 

2. Select a feature type from the list box beneath the Feature type field or type the 
name in the field. 

Visual Builder displays the type that you select (attribute, event, or action) in the 

the Feature type field. 

3. Select the feature that you want to promote from the list box beneath the 
Promotable feature field or type the name in the field. 

Visual Builder displays the feature that you select in the Promotable feature 
field. 

4. Do one of the following: 

• If you want to promote the feature using the default name that Visual Builder 
provides, select the Add with defaults push button. 

Visual Builder promotes the feature and displays the feature name in both the 
Promote feature name field and in the list box below this field. 

• If you want to see the default feature name that Visual Builder provides 
before you promote the feature, select the Defaults push button. 

Visual Builder displays the default name for the feature in the Promote 
feature name field. 

• If you want to promote a feature after seeing its default name or typing 
another name that you prefer, select the Add push button. 

Visual Builder promotes the feature using the name in the Promote feature 
name field and displays the name in the list box below this field. 

Changing a Promoted Feature 

To update a feature that you have already promoted, do the following: 

1. Select the promoted feature that you want to update. 

2. Select those aspects of the promoted feature that you want to update in the fields 
on the right side of the Promote page. You can select any or all of the 
following: 

• Subpart name 

• Feature type 
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• Promotable feature 
3. Select the Update push button. 

Visual Builder updates those aspects of the feature that you selected. 

The only noticeable change is the subpart name if you selected a different one. The 
subpart name shown in parentheses behind the promoted feature name changes if you 
selected a different subpart. For example, suppose you promoted the 
buttonClickEvent feature of PushButtonl and then realized you should have promoted 
the buttonClickEvent feature of PushButton2. Instead of deleting the promoted 
feature, you can update it by changing only its subpart. 

Deleting a Promoted Feature 

To delete a promoted feature, do the following: 

1. Select the promoted feature that you want to delete. 

2. Select the Delete push button. 

Visual Builder deletes the promoted feature from the list box beneath the 

Promote feature name field. 

Note: If you added the promoted feature that you just deleted to the preferred 
features list, you must go to the Preferred page and delete it there, too. 

Clearing the Promote Page Fields 

To clear the fields on the Promote page, select the Clear push button. Visual 
Builder removes the information from all of the fields on the page. 

The Preferred Page 

Use the Preferred page of the Part Interface Editor to specify the preferred features 
for your part—the features that you use most often when connecting this part to 
another part. The features (attributes, events, and actions) that you specify appear in 
the pop-up menu that is displayed when you begin a connection on this part. You 
can include any features that exist for your part, as well as any features that your part 
inherits from other parts. 
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Figure 20. The Preferred Page of the Part Interface Editor 

In addition to these features, the pop-up connection menu contains the More-^- 
selection. This selection allows you to display a window that contains all of the 
features for this part, as well as the features it inherits. Visual Builder provides this 
window in case you need a feature that is not in the preferred features list. 

The names of the part’s features are displayed in the list boxes named Actions, 
Attributes, and Events on the left side of the page. The preferred features are 
displayed in the Preferred Features list box on the right side of the page. 
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Adding a Preferred Feature 

To add a preferred feature to the connection menu for a part, do the following: 

1. Select a feature name from one of the list boxes on the left side of the page. 

2. Do either of the following: 

• Select the Add push button at the bottom of the page. 

• With the mouse pointer still over the list box in which you selected the 
feature name, do the following: 

a. Click mouse button 2. 

A pop-up menu with the Add choice appears. 

b. Select Add to add the feature. 

The feature name that you selected is inserted into the Preferred Features list 
box in alphabetical order. 

Removing a Preferred Feature 

You can remove a preferred feature name from the connection menu for a part. 

Doing this removes the feature from the menu only; it does not delete the feature. 

To remove a preferred feature from the connection menu for a part, do the following: 

1. Select the name that you want to remove from the Preferred Features list box. 

2. Do either of the following: 

• Select the Remove push button at the bottom of the page. 

• With the mouse pointer still over the feature name in the Preferred Features 
list box, do the following: 

a. Click mouse button 2. 

A pop-up menu appears. 

b. Select Remove to remove the selected feature. 

A message box is displayed to make sure you want to remove the name of this 
preferred feature. 

3. Select Yes to remove the feature name from the list. 

The feature name that you selected is removed from the list. 
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Removing All Preferred Features 

You can remove all of the feature names from the connection menu for a part. Doing 
this removes the features from the menu only; it does not delete the features. Once 
you remove all preferred features from the connection menu, you must select More to 
use the features in a connection. 

To remove all of the preferred features from the connection menu for a part, do either 
of the following: 

• Select the Remove all push button at the bottom of the page. 

• With the mouse pointer over the Preferred Features list box, do the following: 

1. Click mouse button 2. 

A pop-up menu appears. 

2. Select Remove all to remove all of the selected features. 

A message box is displayed to make sure you want to remove all of the preferred 
features. 

Select Yes to remove all of the feature names from the list. All of the feature names 
are removed from the list. 

Showing Inherited Preferred Features Only 

To show only the preferred features that your part inherits from other parts, select the 
Default push button. 

A message box is displayed. Select Yes to display only the inherited preferred 
features. 
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Part 3. Developing Visual Builder Applications 

This part provides the information you need to create a basic Visual Builder 
application. 
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When designing your applications, remember that Visual Builder implements parts as 
C++ classes. Therefore, keep in mind good design practices and techniques that 
apply to both classes and parts. 

At the heart of Visual Builder lies visual programming and construction from parts. 
The predefined palette of reusable parts coupled with the Composition Editor provide 
a new level of power in developing applications. Of course, increased power does 
not guarantee good design and improved productivity, so the following sections are 
provided to assist you in designing more effective Visual Builder applications. 


Designing Parts for a Single Purpose 

Much like designing the user interface of any application, you need to design each 
part in your Visual Builder application for a single purpose. For example, consider 
an application that queries a simulated database for information about contractors, 
their skills, and the contracts to which they are assigned. These queries clearly 
identify the three actions that can be performed using the application. Therefore, this 
application needs a separate part that shows the results of each query. 

These parts could include a notebook that displays information about individual 
contractors, a window with entry fields that contain information about a specific 
contract, and a container that shows which contractors have a certain skill. Each of 
these specific queries becomes the single purpose around which you design your 
parts. Of course, supporting parts such as a main window for starting the queries, 
nonvisual parts that supply the results of a search, and dialogs for specifying the 
search targets are also required. 

You can then combine your parts into a single business-wide application that can be 
shared by multiple users. Each user has direct access to the parts needed to complete 
a specific query without interference from any parts of the application that are 
conducting other queries. 

In “Designing Parts for the OASearch Application” on page 90, we introduce a 
sample application that can perform the queries described in this section and explain 
the design of each of the application’s parts. 
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Taking the Object-Oriented Approach 

Object-oriented design seeks to find parallels between computer entities and 
real-world entities. By not blurring the lines between the roles and tasks of the 
business, and by providing a part for each, you effectively provide a computer 
application that parallels the way your business operates in the real world. 

Thinking more closely in terms of Visual Builder and the Composition Editor, parts 
that are too large can have a negative effect on usability, performance, and 
maintenance. As a general rule, for each part, you want to use the minimum number 
of visual parts, nonvisual parts, connections, and parameters necessary to achieve a 
single purpose. 

In addition, try to use attributes whenever possible instead of actions. 
Attribute-to-attribute connections, for example, tend to minimize the number of 
required connections because usually you do not need any additional connections to 
provide a parameter as you do with actions. 

Here is a sample list of steps you might follow to create an OO application using 
Visual Builder: 

1. Design the application. 

• Decide which tasks and functions you want the application to perform. 

• Determine how you will represent those tasks and functions on the interface. 

• Design the user interface, deciding which windows the application displays. 

• If more than one window is involved, decide which one is to be the main 
window. The main window normally consists of the following: 

- The window that users first see when they start the application 

- Any other visual parts that are included in the window, such as list 
boxes, entry fields, and push buttons 

- Any nonvisual parts that are needed, such as object factories 

• Decide which parts the application needs in order to provide those windows 
and to suppoit the task a user wants to accomplish. 

• Decide which member functions the parts need by determining what 
messages need to be sent from one object to another. 

• Decide which data members the parts need by determining the various types 
of data the part is to provide. 

• Decide which features (attributes, events, and actions) the parts need. 
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• Decide which features of each part need to be connected to features of 
another part. For example, a Close push button can close a window only if 
its buttonClickEvent feature is connected to the window’s close action. 

2. Create any parts you need that Visual Builder does not already provide, or that 
someone else has not already created. 

3. Create the main window and any other required windows using the parts and 
connections predetermined in the previous steps. 

4. Generate the C++ code for the application. 

5. Make any necessary modifications to the generated C++ feature code. 

6. Build and run the application. 

Developing an OO application is a process in which these (and perhaps other) steps 
are usually repeated many times. For that reason, the preceding steps are provided 
merely as an example. You might not follow them exactly in the order given when 
creating your applications. For example, you might not realize that you need to 
create a certain part until you have already started creating a composite part. 

The next section, “Identifying Reusable Parts,” suggests ways to get the most from 
parts, once you have settled upon their high-level design. 


Identifying Reusable Parts 

Once you have the high-level design of your application's parts, identify common 
elements. These common elements are perfect opportunities for reuse. Make them 
into reusable parts and add them to the parts palette. 

For example, go back to the application that queries for contractor, skill, and contract 
information. Consider the visual part that displays information about an individual 
contractor. Along with the information supplied for each contractor is the 
contractor’s name and address. You can make this common address element into a 
reusable, composite visual part that looks like this: 


Home Address 
Street | 

City |_ 

State [ Postal Code 


Figure 21. Reusable Address Part 
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You can then reuse the same address part in visual parts for other applications you 
create. By reusing parts, you increase productivity. For example, you only have to 
lay out the form once. In addition, because the State and Postal code field formats 
differ from the default formats used by the other fields, you only have to set the 
formats for these fields once, as well. 

You also get the potentially more important benefit of improved maintenance. For 
example, if an error is discovered, you only have to fix it in one place. Or later, if 
your business decides to start using an Auxiliary address field, you would only have 
to make the change once to your visual address part. 

Likewise, if the business grows into worldwide sales, then you could change State to 
State/Region, and add a Country field (provided you are using a database that can 
accommodate such changes). Having to make these changes only once saves time. 

The next section, “Using Inheritance,” suggests more ways to reuse parts. 


Using Inheritance 

As you are scanning your application looking for common elements, do not overlook 
the possibility of reusing an entire part. You can reuse both nonvisual and class 
interface parts. 

Many times, you need parts that are similar to ones you have already built. 

Inheritance gives you an easy way to make new parts from the ones you already 
have. Reusing existing parts through inheritance saves most of the work that would 
usually be required to create a new part. 

Example 

Suppose you created a new nonvisual part named Person. You could use inheritance 
to build a derived Contractor part that inherits the Person part’s features and has other 
features of its own. The following example assumes you have already created a 
nonvisual Person part. 

1. Begin in the Visual Builder window by selecting Part—^New. 

The following window is displayed: 
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Figure 22. Part — New Window 

2. Type Contractor in the Class name field. 

3. Change the part type to Nonvisual part in the Part type field. 

4. Enter Person in the Base class field. 

Your new Contractor part now inherits from your Person part. Your window 
looks like the following: 



Figure 23. Part — New Window with Person Part as Base Class 

5. Select Open to create the part and open the Part Interface Editor. 

When the Part Interface Editor opens, it displays the Attribute page. 

6. Add new attributes that a contractor might have, such as startDate, endDate, and 
activeStatus. 
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The next section, “Using Abstract Classes” on page 88, suggests ways to factor out 
common classes and member functions so you can better reuse the code that you 
write. 


Using Abstract Classes 

The technique of scanning your application for common elements applies as much to 
code as it does to visual parts. 

As you are writing member functions that enhance your visual parts, look for 
common member functions. These common member functions indicate perfect 
opportunities for reuse and can possibly be placed in an abstract class. 

Abstract classes are used for factoring out common behavior. They are not intended 
to define any particular real part. Therefore, never represent an abstract class as a 
part on the free-form surface of the Composition Editor. Instead, use the abstract 
class as the base class, or as an ancestor of the base class, of nonvisual or class 
interface parts that you create and place on the free-form surface. 

Abstract classes are repositories for common member functions. The similarities 
between your various parts determine which member functions are candidates to be 
grouped together under a common abstract class. 

e 


If you move a member function from a part to an abstract class, remove 
that member function from the interface of the part from which it was 
removed. You are not required to do this, but maintaining your application 
is easier if each part properly reflects only the member functions it contains 
in its part interface. 


All of the benefits of reuse are achieved, namely increased productivity and reduced 
maintenance, from only having to write and maintain the member functions in one 
place. 

The next section, “Keeping Your Components Small” on page 89, emphasizes a 
common theme in designing effective Visual Builder applications. 
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Keeping Your Components Small 

As the topics in this chapter have probably made clear by now, a primary goal of any 
object-oriented environment, including Visual Builder, is reuse, for which keeping 
your components small is fundamental. The smaller you make the components of 
your applications, the more opportunity you have to take advantage of reuse. 


The following table provides the numbers, based on C++ research, that you should 
aim for in creating your classes, member functions, and data members. 


Criteria 

Optimum number 

Reason 

Average lines per member 
function 

Fewer than 24 

A higher average generally 
indicates poor object-oriented 
design and a tendency toward 
function-oriented 
programming. 

Average member functions 
per class 

No more than 20 

Higher averages indicate you 
can distribute your member 
functions among more 
classes. 

Average data members per 
class 

No more than six 

Higher averages indicate you 
can distribute your data 
members among more 
classes. 

Average number of base 
classes per class 

No more than six 

Inheriting from too many 
classes indicates too few 

member functions in each 

class. This can cause 
performance and size 
problems because the more 
base classes from which your 
classes inherit, the slower 
your compiled code runs and 
the larger it becomes. 


These numbers generally depend on the complexity of the class. Less complex 
classes that take full advantage of prewritten reusable parts typically have fewer 
member functions per class. Also, the number of data members depends on how 
data-intensive the classes are. However, many of the member functions and data 
members you need can be inherited by default from classes provided by Visual 
Builder. 

Applying the design strategies covered in these sections and gaining experience 
should help you achieve these averages. 
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Designing Parts for the OASearch Application 

A sample application is used in this part of the book to show you how to build a 
simple GUI application. You can find the nonvisual parts in oanonvis.vbb. All 
visual parts are in oawin.vbb. For in-depth information about designing your own 
parts, refer to Building Visual Age C++ Parts for Fun and Profit. 

This application, called OASearch, serves recruiters for a fictitious technical 
contracting services firm, called Opportunities Abound (OA). Customers call OA to 
request temporary help; recruiters use the application to match skill requirements with 
available contractors. When matches are made, the recruiters enter contract 
information into the application. 

Using a Simulated Database 

This sample application does not require the installation of a database program. 
Instead, the application uses the IProfile class to create and maintain a simple 
database in three .ini files. To see the implementation, browse the following code 
files; 

contrctr.cpv 
contract.cpv 
skillb.cpv 

For more information about the IProfile class, refer to the IBM Open Class Library 
Reference. 

Designing Nonvisual Parts 

When designing your own application, take extra time to think through the nonvisual 
parts. One way to minimize rework during design is to use index cards, putting the 
data and tasks of each part or class on a separate card. This method enables you to 
throw away one design in favor of another, rearranging the cards until you are 
confident of your design. 

The OASearch application uses the following nonvisual parts to hold or manage data: 

• OAContractor, which represents OA employees 

• OAContract, which represents OA contracts 

• OASkill, which represents marketable skills held by OA’s employees 

• OASkillBase, which controls traffic between the OASkillView window and the 
skill database. This is necessary because of the one-to-many relationship that 
exists between OAContractor and OASkill instances. That is, many contractors 
could hold the same skill and a single contractor could hold many skills. 

• SkillList, a part instance of type IVSequence. For more information about 
sequences, refer to the Visual Builder Parts Reference. 
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The OAContractor Part 

When you design a Visual Builder part, you are designing a C++ class. The part 
interface corresponds to the part interface of the underlying class. The class can also 
have member functions (public, protected, or private) that do not exist in the part 
interface. 

OAContractor Attributes 


The OAContractor part has the following attributes: 

• lastName, the contractor’s last name 

• firstName, the contractor’s first name 

• middlelnitial, the contractor’s middle initial 

• homeStreet, the contractor’s home street address 

• home City, the contractor’s home city 

• home State, the contractor’s home state or province 

• homeZip, the contractor’s home postal code 

• phoneNumber, the contractor’s daytime phone number 

• startDate, the date on which the contractor started working at Opportunities 
Abound 

• endDate, the date on which the contractor stopped working at Opportunities 
Abound 

• activeStatus, whether the contractor is interested in a new position 

• currentContract , the contractor’s current assignment (if any) 

• contractorlD, the contractor’s database identifier 

All attributes are of type IString, except for the activeStatus attribute, which is of type 
Boolean. The contractorlD attribute is derived from the contractor’s name attributes. 

To enable you to use these attributes, the contractor part must also contain public get 
and set member functions. By convention, the names of these member functions 
follow a pattern determined by the name of the attribute. For the IString attribute 
lastName, the get member function is called lastName, and the set member function is 
called setLastName. For the Boolean attribute activeStatus, the get member function 
is called isActiveStatus, and the set member function is called enableActiveStatus. 

To retrieve or update contractor information from the database, the OAContractor part 
contains the following actions: 

• getContractor 

OAContractor & getContractor(); 

• parseName 

OAContractor & parseName(const IString & aName); 

• putContractor 
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OAContractor & putContractor(); 

The parseName action parses an input string to set the firstName, middlelnitial, and 
lastName attributes. The getContractor and putContractor actions use the derived 
attribute contractorlD to retrieve and store contractor information in the database. 
The feature code for this part appears in contrctr.cpv. 

For a look at the visual part that OAContractor supports, see “The Opportunities 
Abound Contractor Information Window” on page 96. 

The OAContract Part 

The OAContract part contains the following attributes: 

• accountNum, the contract’s account number 

• companyName, the name of the client company 

• projectMgr, the client company’s representative 

• deptName, the department within the client company that needs a position filled 

• positionTitle, a description of the position to be filled 

• startDate, the first day of work at the client company 

• endDate, the last day of work at the client company 

• currContractor , the identifier of the contractor filling the position 

It also contains the following actions: 

• getContract 

OAContract & getContract(const IString & anAccountNum); 

• putContract 

OAContract & putContract(const IString & anAccountNum); 


All attributes are of type IString. The feature code for this part appears in 
contract.cpv. 

For a look at the visual part that OAContract supports, see “The Opportunities 
Abound Contract Information Window” on page 98. 

The OASkill Part 

The OASkill part contains the following attributes: 

• skillName, a description of the skill required 

• years Exp, the number of years of experience needed 

• contractorlD, the identifier of the contractor holding this skill 

• key, an index used to construct the database key 

All attributes are of type IString. The feature code for this part appears in skill.cpv. 
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For a look at the visual part that OASkill supports, see “The Opportunities Abound 
Skill Information Window” on page 98. 

The OASkillBase Part 

The OASkillBase part contains no attributes but has the following actions: 

• getSkills 

OASkill & getSkills(const IString & aSkillName, IVSequence <0ASkill*> & aList); 

This action retrieves skill information from the database, instantiates OASkill 
objects from retrieved information, and adds pointers for the new objects to the 
specified list of skills. 

• putSkill 

OASkill & putSki11(const OASkill & aSki11); 

This action stores skill information in the database. 

The feature code for this part appears in skillb.cpv. 

For a look at the visual part that OASkillBase supports, see “The Opportunities 
Abound Skill Information Window” on page 98. 

Designing Visual Parts 

Although the OASearch application was designed to illustrate variety more than 
efficiency, consider the following design decisions: 

• The Opportunities Abound Databases window (part OAMain) is the integration 
point for the application. All variables found in the other composite parts are 
resolved in OAMain. All parts except the OASkill search results are instantiated 
here. 

• The connections between visual parts are minimized with the use of promoted 
variables to pass data. Inside each visual part, attribute-to-attribute connections 
load data from the variables into the windows. 

• All views use multicell canvases to hold the primitive visual parts. 

The Opportunities Abound Databases Window 

The welcome window for OASearch appears in Figure 24 on page 94. 
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Opportunities Abound Databases 
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Figure 24. The Opportunities Abound Databases Window (OAMain) 


This first window to appear is the primary view, the part containing this window, 
OAMain, is the main part. To view information, recruiters can use the View 
submenu or press one of the three graphic push buttons. To enter information about 
new contracts or contractors, they can use the Edit submenu. 

This window shows use of the following: 

• Menu bar 

• Embedded multicell canvas 

• Icons as resources 

• Object Factory parts 

• Variables used with Object Factory parts 

The Opportunities Abound General Information Window 

When a user selects General information from the View submenu, the Opportunities 
Abound General Information window appears, as shown in Figure 25 on page 95. 
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Figure 25. The Opportunities Abound General Information Window (OAGenlnfo) 

This window shows use of the following: 

• IViewPort* with multicell canvas 

• Handler class (IVBMinSizeViewPortHandler) for IViewPort* 

This window uses an IViewPort* part as the client. An IMultiCellCanvas* part 
within the IViewPort* holds the IStaticText* parts. In the compiled application, the 
handler resizes the IMultiCellCanvas* whenever the window is resized. 

To see what happens when the handler is not running, open the OAGenlnfo part in 
the Composition Editor. If you resize the IFrameWindow* part, the IViewPort* part 
is resized automatically, but the IMultiCellCanvas* part is not. You must resize the 
IMultiCellCanvas* part manually to fit inside the border of the resized 
IFrameWindow*. 

The Query Windows 

When recruiters select a graphic push button or View menu item from the 
Opportunities Abound Databases, a query window appears, as shown in Figure 26 on 
page 96. 
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Request for Skill Information 
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Enter skill description below: 


OK Cancel Help 


Figure 26. The Request for Skill Information Window (OAQuerySkill) 

The OAQuerySkill part contains this window. Two other parts, OAQueryContract 
and OAQueryContractor, hold other query windows. 

When a user enters a value in the query window and selects the OK push button, the 
query window closes and the corresponding information window appears. If the 
requested value is not found, a message box appears. Users can also get help or 
return to the Opportunities Abound Databases window. 

This window shows use of the following: 

• Modal window display 

• Help enablement 

• Promoted variables features 

The Opportunities Abound Contractor Information Window 

When the requested contractor is found in the contractor database, the Opportunities 
Abound Contractor Information window appears, as shown in Figure 27 on page 97. 
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Figure 27. The Opportunities Abound Contractor Information Window (OAContractorView) 


The application retrieves the records matching the requested contractor identifier, sets 
an OAContractor* part, and displays the values in this window. The Contact page 
contains information about how to get in touch with the contractor. The History 
page contains information about the contractor’s work history. The Skills page is 
provided for users of the sample application to update skills a hypothetical contractor 
has. 

This window shows use of the following: 

• INotebook* part 

• Different multicell canvas layouts 

• Event-to-member function connection 

• Event-to-custom logic connection 

• Variables used as placeholders 

• Promoted features 
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The Opportunities Abound Contract Information Window 

When the requested contract is found in the contract database, the Opportunities 
Abound Contract Information window appears, as shown in Figure 28. 
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Figure 28. The Opportunities Abound Contract Information Window (OAContractView) 

The application retrieves the records matching the requested contract account number, 
sets an OAContract* object, and displays the values in the window. This window 
shows basic multicell canvas layout. 

A variant of the OAContractView part, ContractView, appears in contract.vbb. This 
version of the Opportunities Abound Contract Information window uses an ICanvas* 
part instead of a multicell canvas. It is formatted for an XGA/8514 display. 

The Opportunities Abound Skill Information Window 

When the requested skill is found in the skill database, the Opportunities Abound 
Skill Information window appears, as shown in Figure 29 on page 99. 
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Figure 29. The Opportunities Abound Skill Information Window ( OASkillView) 

The application retrieves all records matching the requested search description, 
creating instantiating an OASkill object for each pair of records (contractor and years 
of experience) found. Each new OASkill object is put into a list and, from there, into 
the container shown in the window. Recruiters can search on other skills without 
leaving this window by typing the new skill description into the entry field and 
selecting the Refresh push button. 

This window shows use of the following: 

• IVBContainerControl* 

• IContainerColumn* 

• IVSequence* 

How the Sample Application Was Built 

The OASearch application was developed in the following order: 

1. The major nonvisual parts were designed. 

2. The major visual parts were designed. 

3. The nonvisual parts were built. 

4. The view parts were built. 

5. The query parts were built. 

6. The OAMain and OAGenlnfo parts were built. 

7. Code for all parts was generated at the same time from the Visual Builder 
window. 
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Creating Nonvisual Parts 


This chapter describes how to define your own parts. For this example, we will 
create a nonvisual part, OAContractor, because it illustrates the process better than a 
visual part. 

For information about using the Composition Editor to create visual parts, see 
Chapter 8, “Learning to Use Parts” on page 115. For more information about using 
the Part Interface Editor to define part interfaces, see “The Part Interface Editor” on 
page 57. 

You create a part by doing the following: 

1. Design the part. (See “Designing Parts for the OASearch Application” on 
page 90.) 

2. Define the part interface, either through the Part Interface Editor or by importing 
a part information file. (See “Defining the Part Interface.”) 

3. Add code to your part. You can use C++ code written outside of Visual Builder, 
or you can generate default feature code in Visual Builder and modify it. (See 
“Adding Code to Your Part” on page 105.) 

If you have previously existing C++ code that you would like to use in your part, the 
following process is probably more efficient: 

1. Design the part. 

2. Define the part interface using part information files. 


Defining the Part Interface 

When you are satisfied with your part’s design, you are ready to define the part 
interface to Visual Builder. 

1. Define the attributes of your part. 

A part’s attributes typically correlate to the class’ data members and can 
additionally include derived attributes, or attributes that are determined based on 
the value of other attributes. 

2. Define the member functions that get or set the value of those attributes. 

3. Define any actions that you want the part to be able to do. 

A part’s actions correlate to the class’ public member functions. 
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4. Specify the event notification identifier used to signal a change in the value of 
each attribute. 

You can define the part interface in either of the following ways: 

• Use the Part Interface Editor. With this method, you create the part from the 
Visual Builder window and then enter each feature of the part interface 
individually using the pages of the Part Interface Editor. 

• Use a part information file. With this method, you encode part information in a 
file and then create the part and its interface by importing the information into 
Visual Builder. This method might be more efficient if C++ code already exists 
for your part. See Chapter 17, “Using Existing C and C++ Code with Visual 
Builder” on page 281 and refer to Building VisualAge C++ Parts for Fun and 
Profit for information about creating part information files. 

Defining the Part Interface Using the Part Interface Editor 

Open a new nonvisual part called OAContractor. The Part Interface Editor appears. 

On the Attribute page, do the following: 

1. Type lastName in the Attribute name text-entry field and select the Add with 
defaults push button. 

Your Part Interface Editor looks like Figure 30 on page 103. 
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Figure 30. Creating the lastName Attribute 

Notice that several default values are displayed: 

• The default Attribute type is IStandardNotifier*. This means that the 
lastName attribute is an instance of the IStandardNotifier* class. 

• The default Get member function, lastName, matches the lastName member 
function of your design. When your contractor part is queried for the value 
of its lastName attribute, it executes the lastName member function to 
retrieve the contractor's last name. 

• The default Set member function is setLastName. When your contractor 
part is passed the name that has been assigned to the contractor, it uses the 
setLastName member function to store the value in its lastName attribute. 

• The default Event notification is lastNameld. When a value is stored in the 
lastName attribute using the setLastName member function, the contractor 
part signals this event to let other parts know that the value has changed. 

For example, if there is an attribute-to-attribute connection between lastName 
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and a label's string value, the label part is informed so that it displays the 
latest value. 

• If needed, you can explain more about the attribute in the Description field. 

2. Change any of the default values, if needed. For this example, change the default 
attribute type to I String. You can do this by typing the value directly into the 
entry field or by selecting the drop-down list box arrow to the right of the entry 
field and selecting I String from the list. 

Also, edit the Get member function and Set member function fields, changing 
IStandardNotifier to IString. This causes these member functions to accept 
IString as a parameter instead of IStandardNotifier. 

3. Select the Update push button to save the changes you just made. 

4. Select the Clear push button to clear the fields before adding the next attribute. 

5. Repeat the previous steps for the contractor's first Name, middlelnitial, 
homeStreet, homeCity, homeState, homeZip, startDate, endDate, currentContract, 
and phoneNumber attributes. For these attributes, specify the IString attribute 
type before selecting the Add with defaults push button in the first step. This 
prevents you from having to change IStandardNotifier* to IString as you did 
previously. 

6. Define the contractorlD attribute as IString, with the following get member 
function: 

OAContractor & getContractorlD (); 

This attribute is derived from other attributes; we will add the code for this later. 
You do not want users to set this attribute directly, so do not include a 
setContractorlD member function. 

7. Define the activeStatus attribute as Boolean. Note that the default get member 
function and set member function follow a different format than the ones for 
IString attributes. 

8. To define the actions for OAContractor, select the Action page. 

9. Type putContractor in the Action name field and the following into the Action 
member function field: 

OAContractor & putContractor(); 

10. Select the Add push button; then select Clear. 

11. Repeat for the getContractor and parseName actions. At this point, the Action 
page appears as shown in Figure 31 on page 105. 
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Figure 31. Adding Actions to the Part Interface Editor 

12. Select Save from the File pull-down menu to save your work. 

The next step is described in “Adding Code to Your Part.” 

Adding Code to Your Part 

Once you have specified the part interface for your part, you are ready to add the 
code to make the part work. Adding code involves the following tasks: 

1. Generating default feature code. If you already have C++ code for your part and 
have imported the part information, this step is not necessary. 

2. Modifying the feature code. 

3. Adding code created outside Visual Builder if it already exists. 
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Generating Default Feature Code 

If code does not already exist for your part, you can use Visual Builder to generate 
default feature code. Default feature code consists of code that is based on the part 
interface you defined earlier. For most attributes, the default feature code is sufficient 
to define get member functions, set member functions, and event notifications. For 
actions, you have to modify the default feature code to add the function or logic you 
want your part to perform. 

If you also use Visual Builder to generate the default source code for your parts, you 
will find it helpful to generate default feature code separately. Each time you 
generate default source code. Visual Builder replaces the existing files with new ones 
because there is no need for you to modify these files. 

The files that you usually need to modify are the default feature code files. These are 
the files in which you write the code to tell your application how to perform the 
actions that you create in the Part Interface Editor. Each time you generate default 
feature code. Visual Builder appends the newly generated code to the end of each 
existing feature code file. This is done so that you will not lose any code that you 
have written. 

In addition, you do not have to generate new code for all of your features each time 
you need default code for a feature. You can create a new feature in the Part 
Interface Editor and then generate default feature code just for the new feature. 

Visual Builder appends the default code for the new feature to end of the existing 
files so that you can modify it. 

Note: If you regenerate default code for a feature, be sure to remove the previous 
code for that feature from the file to prevent compilation errors or unwanted 
results. 

To generate default feature code for the OAContractor part, follow these steps. 

Note: This example is a continuation of the example in the preceding section using 
the OAContractor part, which should be open in the Part Interface Editor. 

W 

1. Switch to the Class Editor by selecting the — icon in the lower-right corner 
of the window. 

2. Specify the .hpv and .cpv files for Visual Builder to use for the default feature 
code for the OAContractor part’s attributes and actions by filling in the following 
fields: 

User .hpv file contrctr.hpv 

User .cpv file contrctr.cpv 
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The Class Editor with the appropriate fields filled in is shown in Figure 32 on 
page 107. 
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Figure 32. Specifying File Names in the Class Editor 

3. Select File-*Save and Generate^* Feature source. 

The Generate feature source code window appears, as shown in Figure 33 on 
page 108. 
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OAContractor - Generate feature source code 
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Figure 33. The Generate Feature Source Code Window 

4 . Generate the default feature code using one of the following methods: 

• Select the Generate all push button to generate default feature code for 
member functions and data members. 

• Select the appropriate member functions and data members from the 

Member functions. Attribute data members, or Event data members list 
boxes. Then, select the Generate selected push button. 

The first time you will probably want to generate code for all of your features. 
Then, you can generate code for other features as you add them. 

For this example, select the Generate all push button. 

The default feature code is stored in the files you specified in the Class Editor, 
contrctr.hpv and contrctr.cpv. If these files already exist, the code you just 
generated is appended to the ends of these files. 

For most parts, you must modify the default code to make your part fully 
functional. 

The next step is modifying the generated feature code. 
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Modifying the Generated Feature Code 

After you have Visual Builder generate the feature code, review it. Does it do what 
you need it to do? If not, modify the code. The OAContractor part needs the 
following changes: 

• Modified code for the getContractor action 

• Modified code for the putContractor action 

• Modified code for the parseName action 

• Added code to set the activeStatus attribute 

• Added code to set the contractorlD attribute 

Modifying Code for the getContractor Action 

This version of our contractor application uses an IProfile-based database to store 
information about the contractors. For our OAContractor part to use this database, 
we must complete the getContractor and putContractor actions and modify the 
activeStatus attribute. The following example shows the default code generated for 
the two actions: 

OAContractor & OAContractor::getContractor() 

{ 

return *this; 

} 


OAContractor & OAContractor::putContractor() 

{ 

return *this; 

} 


To modify default feature code, edit the code files using the syntax text editor 
provided by VisualAge C++ or your favorite editor. Code for our getContractor 
action follows: 

OAContractor & OAContractor::getContractor() 

{ 

// Start data access code 

I Profile *p = new IProfile("contrctr.ini"); 

// Test for missing name information 

// Necessary for proper derivation of the contractorlD attribute 

if ((liLastName) || (!iFirstName) || (!iMiddlelnitial)) 

{ 

throw IException("The contractor's name is incomplete. Complete all name fields and try again."); 
return *this; 

} 


// Refresh the value of contractor ID 
setContractorlDQ; 

// Check for this contractor ID in the profile collection 

if (!p->containsKeyName("contractorID", iContractorlD)) 
{ 
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throw IException("A record was not found for this contractor."); 
return *this; 

} 


// If other data exists for this contractor, 

// set the corresponding contractor attributes 

if (p->containsKeyName("lastName", iContractorlD)) 
setl_astName(p->el ementWi thKey ("1 astName 11 , iContractorlD)); 
if (p->containsKeyName("firstName", iContractorlD)) 
setFirstName(p->elementWithKey("firstName", iContractorlD)); 
if (p->containsKeyName("middleInitial", iContractorlD)) 
setMiddlelnitial(p->elementWithKey("middlelnitial", iContractorlD)); 
if (p->containsKeyName("homeStreet", iContractorlD)) 
setHomeStreet(p->elementWithKey("homeStreet", iContractorlD)); 
if (p->containsKeyName("homeCity", iContractorlD)) 
setHomeCity(p->elementWithKey("homeCity", iContractorlD)); 
if (p->containsKeyName("homeState", iContractorlD)) 
setHomeState(p->elementWithKey("homeState", iContractorlD)); 
if (p->containsKeyName("homeZip", iContractorlD)) 
setHomeZip(p->elementWithKey("homeZip", iContractorlD)); 
if (p->containsKeyName("phoneNumber", iContractorlD)) 
setPhoneNumber(p->elementWithKey("phoneNumber", iContractorlD)); 
if (p->containsKeyName("startDate", iContractorlD)) 
setStartDate(p->elementWithKey("startDate", iContractorlD)); 
if (p->containsKeyName("endDate", iContractorlD)) 
setEndDate(p->elementWithKey("endDate", iContractorlD)); 
if (p->containsKeyName("currentContract", iContractorlD)) 
setCurrentContract(p->elementWithKey("currentContract", iContractorlD)); 

// Call overloaded set member function using string parameter 

if (p->containsKeyName("activeStatus", iContractorlD)) 
enableActiveStatus(p->elementWithKey("activeStatus", iContractorlD)); 

delete p; 

// End data access code 
return *this; 

} 


The getContractor action checks for one possible error condition. If it occurs, the 
action throws an exception. Otherwise, the action retrieves data by contractor 
identifier from the contrctr.ini file. 

In response to these exceptions, the OAContractorView part shows a message box. 
More about the contractor view part appears in “Constructing a GUI: the OASearch 
Application” on page 161. For information about how to handle exceptions visually, 
see “Passing Exceptions to Message Boxes” on page 209. 
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Modifying Code for the putContractor Action 

Code the putContractor action as follows: 

OAContractor & OAContractor::putContractor() 

{ 

// Start data entry code 

I Profile *p = new IProfile("contrctr.ini"); 

// Test for missing name information 

// Necessary for proper derivation of the contractorlD attribute 

if ((liLastName) || (!iFirstName) || (!iMiddlelnitial)) 

{ 

throw IException("The contractor's name is incomplete. Complete all name fields and try again."); 
return *this; 

} 


// Refresh the value of contractor ID 
setContractorID(); 

p->addOrReplaceElementWithKey("contractorlD", contractorlDQ, iContractorlD)); 

// If other data about this contractor exists, update it in the database 
if (lastName) 

p->addOrReplaceElementWithKey("lastName", lastNameQ, iContractorlD)); 
if (firstName) 

p->addOrReplaceElementWithKey("firstName", firstNameQ , iContractorlD)); 
if (middlelnitial) 

p->addOrReplaceElementWithKey("middlelnitial", middlelnitial(), iContractorlD)); 
if (homeStreet) 

p->addOrReplaceElementWithKey("homeStreet", homeStreet(), iContractorlD)); 
if (homeCity) 

p->addOrReplaceElementWithKey("homeCity", homeCity(), iContractorlD)); 
if (homeState) 

p->addOrReplaceElementWithKey("homeState", homeStateQ, iContractorlD)); 
if (homeZip) 

p->addOrReplaceElementWithKey("homeZip", homeZipO , iContractorlD)); 
if (telephoneNumber) 

p->addOrReplaceElementWithKey("telephoneNumber", telephoneNumberQ, iContractorlD)); 
if (startDate) 

p->addOrReplaceElementWithKey("startDate", startDateQ, iContractorlD)); 
if (endDate) 

p->addOrReplaceElementWithKey("endDate", endDate(), iContractorlD)); 
if (currentContract) 

p->addOrReplaceElementWithKey("currentContract", currentContract(), iContractorlD)); 
if (iActiveStatus) 

{ 

p->addOrReplaceElementWithKey("activeStatus", "yes", iContractorlD)); 

} 

el se 

{ 

p->addOrReplaceElementWithKey("activeStatus", "no", iContractorlD)); 

} 


delete p; 

// End data entry code 
return *this; 

} 
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The putContractor action checks for one possible error condition. If it occurs, the 
action throws an exception. Otherwise, the action stores data by contractor identifier 
in the contrctr.ini file. 

In response to these exceptions, the OAContractorView part shows a message box. 
More about this part appears in Chapter 12, “Constructing Containers and 
Notebooks” on page 235. For information about how to handle exceptions visually, 
see “Passing Exceptions to Message Boxes” on page 209. 

Modifying Code for the parseName Action 

The parseName action parses input text from the Request for Contractor Information 
window and sets the contractor’s firstName, middlelnitial, and lastName attributes. 
Add code as follows: 

OAContractor & OAContractor::parseName(const IString & aName) 

{ 

// aName is supplied by user in OAQueryContractor 
// Test for missing information in newly entered name 

if (aName.numWords()!= 3) 

{ 

throw IException("The name you entered is incomplete. 

Enter first name, middle initial, and last name."); 

return *this; 

} 


// Set name attributes and derive contractorlD attribute 

setFirstName(aName.word(l)); 
setMiddlelnitial(aName.word(2)); 
setl_astName(aName.word(3)); 
setContractorlD; 

// End added code 

return *this; 

} 
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Adding Code to Set the activeStatus Attribute 

You must add a member function to pass string data to the one Boolean attribute, 
activeStatus. All data in our simple database is stored as strings, but the set member 
function for the activeStatus attribute takes a Boolean as a parameter. Because only 
OAContractor’s two actions use this member function, it is not necessary to add this 
to the part interface for OAContractor. However, you must add the member function 
prototype to the contrctr.hpv file. 

The following example shows both the default feature code and the added code in 
contrctr.cpv: 

Boolean OAContractor::isActiveStatus() const 

{ 

return iActiveStatus; 

} 

OAContractor & OAContractor::enableActiveStatus(const Boolean enable) 

{ 

if (iActiveStatns != enable) 

{ 

iActiveStatus = enable; 

notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this)); 

} // endif 
return *this; 

} 


// Start Boolean string enabler 

OAContractor & OAContractor::enableActiveStatus(const IString & status) 

{ 

Boolean tempBoolean = iActiveStatus; 
if (status = "yes") iActiveStatus = true; 
if (status = "no") iActiveStatus = false; 
if (tempBoolean != iActiveStatus) 

{ 

notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this)); 

} 

return *this; 

} 


// End Boolean string enabler 

iActiveStatus is the private data member that corresponds to the activeStatus attribute. 

The notifyObservers function signals that the value of the activeStatus attribute has 
changed. For more information about notification, see Building VisualAge C++ Parts 
for Fun and Profit. 
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Adding Code to Set the contractorlD Attribute 

Now, add code to derive the value of the contractorlD attribute. The following 
example shows the code as modified in contrctr.cpv: 

OAContractor & OAContractor::setContractorID() 

{ 

IString tempString = iFirstName+iMiddlelnitial+iLastName; 
if (iContractorlD != tempString) 

{ 

iContractorlD = tempString; 

notifyObservers(INotificationEvent(OAContractor::contractorIDId, *this)); 

} // endif 
return *this; 

} 


Adding Code Created Outside Visual Builder 

To include previously existing member function code with generated class 
declarations, do the following: 

1. Change the file extension of .cpp files to .cpv. 

2. Change the file extension of .hpp files to .hpv. 

3. Change the file extension of any .rc files to .rev. 

4. Add these files to the Class Editor for the appropriate part. 

If you prefer not to use Visual Builder to develop the code for a nonvisual part but 
you want to be able to use it in the Composition Editor, you can do the following: 

• Write the code. 

• Compile it into a .lib file. 

• Define the part interface using a part information file. 

• Import the part information file. 

For more information on part information files, see “Defining the Part Interface Using 
Part Information Files” on page 281. 
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Learning to Use Parts 


This chapter provides general information on using parts, and then shows you how 
some of this information can be applied to an actual application—the OASearch 
sample application that was introduced in “Designing Parts for the OASearch 
Application” on page 90. 

With the Composition Editor you can visually construct an application by placing 
parts on the free-form surface and making connections between them. 

With connections, you can construct the interactions between the parts of the 
application. For information about connecting parts to each other, see Chapter 9, 
“Learning to Use Connections” on page 167. 

In Visual Builder you use the following kinds of parts: 

• Visual parts, such as IPushButton*, IListBox*, and IEntryField*, to construct the 
graphical user interface (GUI) of the application. 

• Nonvisual parts, such as the sample ICustomer and ICompany parts, to represent 
the data or objects manipulated by the application. 

• Class interface parts, such as IDate* and ITime*, to represent data or objects, 
also. The difference between nonvisual parts and class interface parts is that 
nonvisual parts can notify other parts when an event occurs or an attribute value 
changes; class interface parts, however, do not have this notification capability. 


Working with Parts in the Visual Builder Window 

The topics in this section describe how to perform various actions on part classes 
from the Visual Builder window. 

Displaying Part Names 

To display the names of the parts in a .vbb file, in the Loaded Files list box in the 
Visual Builder window select the .vbb file whose parts you want to see. The names 
of the parts contained in the .vbb file that you selected are displayed in the Visual 
Builder window. Visual parts are displayed in the Visual Parts list box; nonvisual 
parts and class interface parts are displayed in the Nonvisual Parts list box. 

Once part names are displayed, you can perform actions on them, such as opening or 
deleting them. If you need information about loading .vbb files, see “Loading Part 
Files” on page 33. 


© Copyright IBM Corp. 1992, 1995 


115 






Developing Applications 


Figure 34 on page 116 shows the Visual Builder window with the names of the parts 
in the vbbase.vbb file displayed: 


g Visual Builder - D:\IBMCPP\DDE4VB\ 


File Part Edit Options Help Debug 
Loaded Part Files 


D:\IBMCPP\DDE4VBWBBase.vbb 


Visual Parts Nonvisual Parts 


lAnimatedButton 


lOString 


IBaseComboBox 


lAccelerator 


IBaseListBox 


lACollection 


IBaseSpinButton 


lAOrderedCollection 


IBitmapControl 


lApplication 


IButton 


lASequence 


ICanvas 


lASequentialCollection 


ICheckBox 


IBase 


ICircularSlider 


IBitFlag 


ICollectionViewComboBc 


ICLibErrorlnfo 


ICollectionViewListBox 

- 

IClipboard 

- 

|_|_IJJ 



Figure 34. Visual Builder Window with vbbase.vbb Parts Displayed 


Selecting All Parts 

To select all of the parts in the selected .vbb files, select Edit^Select all parts. 

At this point, you can review the list to see if you want to deselect any of the parts. 
You can do so by pressing the Ctrl key and clicking on the part name with mouse 
button 1. 

Deselecting All Parts 

To deselect all of the parts in the selected .vbb files, select Edit—^Deselect all parts. 
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Importing Part Information 

Using any text editor, you can create files called part information files, which are 
used to import existing C++ classes into Visual Builder as parts. Part information 
files are normally recognizable by their .vbe. extension. 

The import part information function loads part information files so that you can use 
the parts specified in those files in Visual Builder. 

To import part information, do the following: 

1. Select File-^Tmport part information. 

The following window is displayed: 


Import Part Information 


Open filename: 
jSMila 


Type of file: Drive: 

<Ail Files> js D: [PROGRAMS] 

File: Directory: 

QIBMCPP 


= DDE4VB 


Q FETest 

□ FETest2 

□ ToDoListZ 


itemlist.vbe 

todoitem.vbe 

TODOLIST.VBE 


OK 

Cancel 




Figure 35. Window for Importing Part Information Files 

2. Select the part information file that you want to import. 

3. Select the OK push button. 

The part information in the part information file is imported. Any visual parts 
that the part information file contains are displayed in the Visual Parts list box, 
and any nonvisual parts and class interface parts it contains are displayed in the 
Nonvisual Parts list box. In addition, one or more .vbb files may be created. 

For more information about using and creating part information files, see the 
following: 

• “Defining the Part Interface Using Part Information Files” on page 281 

• Building VisualAge C++ Parts for Fun and Profit 
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Exporting Part Information 

Just as you can import part information from an existing part information file, you 
can also export part information for any Visual Builder part into a .vbe file. 

The Export interface function creates a part information file that you can, for 
example, use to share nonvisual and class interface parts with other programmers. 

Part information files contain usage information that programmers who do not have 
access to the part (.vbb) file can use. 

To export part information, do the following: 

1. Select the part or parts whose information you want to export in either the Visual 
Parts list box, the Nonvisual Parts list box, or both. 

2. Select Part—^Export interface. 

The following window is displayed: 


Part - Export Interface 


Open filename: 


Type of file: 

Drive: 

<AII Files> 

[s] |P: [PROGRAMS] ~~|*| 

File: 

Directory: 

Address.vbb 

HalBMCPP 

Buttons.cpp 


Buttons.h 

QFETest 

Buttons.hpp 

□ FETest2 

Buttons.obj ^ 

|aToDoList2 




OK 

Cancel 




Figure 36. Window for Exporting Part Information Files 

3. Type the name of the .vbe file in which you want the part information to be 
stored in the Open filename field. 

If you do not enter a file name. Visual Builder uses exported.vbe as the default 
file name. 

4. Select the OK push button. 

The part information maintained by Visual Builder is exported to the file name 
you specified in the Open filename field. 

For more information about using and creating part information files, see the 
following: 
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• “Defining the Part Interface Using Part Information Files” on page 281 

• Building VisualAge C++ Parts for Fun and Profit 

Creating a New Part 

This section provides only the basic steps for creating a new part. For a description 
of how to create a part that others can reuse, see Chapter 7, “Creating Nonvisual 
Parts” on page 101. 

To create a new part, do the following: 

1. Select Part-*New. 

A Part — New window is displayed, as follows: 



Figure 37. Part — New Window 

2. Enter the name that you want to give to your part in the Class name field. 

3. Enter a description of your part in the Description field. 

Visual Builder uses the description that you enter here in the following ways: 

• If you add the part that you create to the parts palette. Visual Builder 
displays the part’s description in the information area at the bottom of the 
Composition Editor when the part is selected. 

• If you export the information about the part to a .vbe file, the description is 
included with the other information about the part. 

4. Enter the name of the .vbb file in which you want Visual Builder to store the 
part in the File name field. 

If the file does not already exist. Visual Builder creates it for you. If you leave 
this field blank. Visual Builder creates a .vbb file as follows: 
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• If you are using the High Performance File System (HPFS) and do not select 
Options—^Default to FAT file names, the name of the .vbb file is the same 
as the name of your part. 

• If you are using the File Allocation Table (FAT) file system and have 
selected Options—^Default to FAT file names. Visual Builder creates a .vbb 
file whose name has no more than eight characters. Without this selection. 
Visual Builder attempts to create a .vbb file whose name is the same as the 
name of your part, which causes an error if your part name has more than 
eight characters. 

Note: If you are using the FAT file system, we recommend that you always 
use part names and file names that have eight characters or less, even 
if you have selected the Default to FAT file names option. 
Otherwise, Visual Builder might use a file name for a .vbb file that is 
the same as one that already exists and write over the existing file. 

5. Select the type of part that you want to create in the Part type field. You can 
select one of the following: 

• Visual part 

• Nonvisual part 

• Class interface 

6. Either keep the default class name provided by Visual Builder in the Base class 
field, change it, or delete it. 

Note the following: 

• A nonvisual part must have the IStandardNotifier class in its inheritance so it 
can exhibit the behavior required for all parts—a part interface (attributes, 
events, and actions). It must inherit this behavior from IStandardNotifier. 
Therefore, you cannot leave this field blank when creating a nonvisual part. 
The default base class for a nonvisual part is IStandardNotifier. 

• A visual part must have the IWindow class in its inheritance so it can inherit 
the visual behavior common to all windows, as well as part interface 
behavior, which IWindow inherits from IStandardNotifier. Therefore, you 
cannot leave this field blank when creating a visual part. The default base 
class for a visual part is IFrameWindow, which inherits from IWindow. 

• No inheritance is required for a class interface part. Therefore, you can 
leave the Base class field blank when creating a class interface part. The 
default base class for a class interface part is IVBase*. 

7. Select Open. 

One of the following occurs: 

• If you are creating a visual part, the Composition Editor is displayed. 
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• If you are creating a nonvisual part or a class interface part, the Part 
Interface Editor is displayed. 

8. Use the displayed editor to create your part. 


Opening Parts 

Use Part^Open to open parts that are already created. You must load the .vbb file 
that contains a part before you can open the part. 




to represent the unloaded 


Visual Builder uses the question mark icon, 
parts on the free-form surface. If you open a part that contains other parts and the 
.vbb files that contain the other parts are not loaded. Visual Builder displays this icon. 


The question mark folder icon indicates that most of the information about the 
unloaded part is not available to Visual Builder. You can select connections between 
unloaded parts and other parts to see which features are connected, but the features 
are not available in the unloaded part’s connection menu. 


You should not make any changes to an unloaded part or generate any code when a 
part is not loaded. 

If you open a part and see a question mark folder icon, do the following: 

1. Close the part you just opened. 

2. Load the .vbb file that contains the unloaded part. 

3. Reopen the part you previously opened. 

The question mark folder icon is replaced by the part’s icon. 

The following instructions tell you how to open one part at a time or multiple parts 
simultaneously. 

Opening one part 


To open one part, do the following: 

1. Find the name of the part that you want to open by scrolling through the 
appropriate list box in the Visual Builder window. 

Note: If the list boxes in the Visual Builder window are empty or if you cannot 
find the part, the .vbb file that contains the part you want to open is not 
selected or not loaded. See “Loading Part Files” on page 33 if you need 
help loading .vbb files. 
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The Visual Builder window with parts loaded from the vbbase.vbb file is shown 
in Figure 34 on page 116. 

2. Select the part you want to open. 

3. Select Part on the menu bar. 

4. Select Open in the pull-down menu. 

One of the following occurs: 

• If you are opening a visual part. Visual Builder displays the Composition 
Editor. 

• If you are opening a nonvisual part. Visual Builder displays the Part 
Interface Editor. 

O 


A quicker way to open an existing part is to double-click on the part name 
within the Visual Parts or Nonvisual Parts list box. 


Opening multiple parts 

To open multiple parts, do the following: 

1. Find the name of the first part that you want to open by scrolling through the 
Nonvisual Parts and Visual Parts list boxes shown in the Visual Builder 
window. 

Note: If the list boxes in the Visual Builder window are empty, see “Loading 
Part Files” on page 33 if you need help loading .vbb files. 

The Visual Builder window with parts loaded from the vbbase.vbb file is shown 
in Figure 34 on page 116. 

2. Select the first part you want to open. 

3. Find the next part you want to open and press the Ctrl key while selecting that 
part. 

4. Continue finding and selecting parts in this manner, pressing the Ctrl key while 
selecting each part, until you have selected all the parts you want to open. 

5. Select Part on the menu bar. 

6. Select Open in the pull-down menu. 

Visual Builder displays a separate window for each part that you selected. The 
window displayed is the Composition Editor for visual parts or the Part Interface 
Editor for nonvisual parts. 
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Copying Parts from One .vbb File to Another 

To copy a part, do the following: 

1. Select the part that you want to copy in the Visual Parts or Nonvisual Parts list 
box. 

If you select more than one part or if you do not select a part, the Copy function 
is not available. 

2. Select Part-^Copy. 

The following window is displayed: 


Part - Copy 


Source part name OAContractorView 


!□] 



Figure 38. Copy Part Window 


The Source part name field shows the name of the part that you selected to 
copy. 

3. In the Target part name field, enter the name you want the part to have when 
you copy it. 

4. In the Target file name field, enter the name of the .vbb file to which you want 

to copy the part. If you leave this field blank, the part’s current file name is 

used. 

5. Select the Copy push button. 

The part is copied under the new name and stored in the designated .vbb file. 

Moving Parts to a Different .vbb File 

Here is what happens to the .vbb file into which the part or parts are being moved: 

• If this .vbb file does not exist. Visual Builder creates and loads it for you. 

• If this .vbb file already exists and is loaded, the part or parts are moved into it. 

• If this .vbb file already exists but is not loaded. Visual Builder displays a 

message to warn you that the unloaded .vbb file will be overwritten by the part 
or parts that you are moving into it. 

To move one or more parts from one .vbb file to another, do the following: 
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1. Select the part or parts that you want to move. 

If you do not select at least one part, the Move function is not available. 

2. Select Part-*Move. 

3. Use the following instructions for moving one part or multiple parts: 

Moving one part 

If you selected one part, the following window is displayed: 


Part - Move 


Part name OAContractorView 


File name D:\IBMCPP\DDE4VB\oawin.vbb 
New file name D:\IBMCPP\DDE4VB\ctrparts.vbb 


Move 


Cancel 


Help 


□ 


Figure 39. Move Part Window for Moving One Part 

The Part name field of this window shows the name of the part that you 
selected to move. The File name field displays the complete path of the .vbb 
file that contains the part you want to move. 

Do the following: 

a. In the New file name field, enter the path and name of the .vbb file to which 
you want to move the part. 

b. Select the Move push button. 

The part is moved to the .vbb file specified in the New file name field. 
Moving multiple parts 

If you selected more than one part, the following window is displayed: 



Figure 40. Move Part Window for Moving More Than One Part 
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The text in the window specifies the names of the parts you selected. 

Do the following: 

a. In the entry field, enter the name of the .vbb file to which you want to move 
the parts. If the .vbb file is not in your current directory, specify the 
complete path for the .vbb file. 

b. Select the OK push button. 

The parts are moved to the .vbb file specified in the entry field. 

An alternate method of moving a part is to change the name of the .vbb file 
specified in the Class Editor. For more information, see “Moving a Part to 
a Different .vbb File” on page 53. 


Deleting Parts from a .vbb File 

To delete a part, do the following: 

1. Select the part or parts that you want to delete in the Visual Parts list box, 
Nonvisual Parts list box, or both. 

If you do not select at least one part, the Delete function is not available. 

2. Select Part—^Delete. 

The following window is displayed: 



Figure 41. Delete Parts Window 

Deselect any parts that you do not want to delete. Once you delete a part from a 
.vbb file, you cannot recover it unless you have another copy stored in another 
.vbb file. 


3. Select the Delete push button. 
The selected parts are deleted. 
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Renaming Parts in .vbb Files 

The Part—^Rename menu choice allows you to change the name that a part is stored 
under in a .vbb file. 


O 


Use care when renaming parts because the name changes only in the .vbb 
file in which the part is stored. The name of the part does not change in 
any other part in which this part is embedded, that is, used as a subpart. 
Therefore, the next time you open the part in which you embedded the 
renamed part. Visual Builder will not be able to find the renamed part. 


To rename a part in a .vbb file, do the following: 

1. Select the part that you want to rename in the Visual Parts or Nonvisual Parts 
list box. 

If you select more than one part or if you do not select a part, the Rename 
function is not available. 

2. Select Part—^Rename. 

The following window is displayed: 



Figure 42. Rename Part Window 

The Part name field shows the name of the part that you selected to rename. 

3. In the New part name field, enter the new name that you want to give the part. 

4. Select the Rename push button. 

The part is renamed under the new name. 
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Working with Parts on the Free-form Surface 

In the Composition Editor, you place visual, nonvisual, and class interface parts on 
the free-form surface. This section explains how to place parts there that appear on 
the parts palette, as well as parts that do not appear on the parts palette. 

Placing a part that appears on the parts palette 

1. From the left column of the parts palette, select the appropriate category. Then, 
from the right column, select the part you want to add. 

When the mouse pointer is moved over a place where the part can be placed, it 
changes to a crosshair, indicating that it is loaded with the part. 

2. Move the mouse pointer to where you want to add the part. 

3. Click mouse button 1. 

If you hold down mouse button 1 instead of clicking it, an outline of the part is 
displayed under the pointer to help you position the part. After the part is in 
position, release mouse button 1. 

See “The Parts Palette” on page 46 and “The Free-form Surface” on page 50 for 
more information. 


To unload the mouse pointer at any time, do either of the following: 


• Select 



, the Selection tool, on the tool bar. 


• Select Tools—s-Selection Tool on the menu bar. 


e 


To add several copies of the same part, select Sticky on the parts palette. 
When Sticky is selected, the mouse pointer remains loaded with the part 
you last selected. When Sticky is not selected, the mouse pointer becomes 
unloaded after you add a part. 


Placing any part whose .vbb file is loaded 

You can place on the free-form surface any part whose .vbb file is loaded by doing 
the following: 

1. Select Add part from the Options pull-down menu. 

The Add Part window appears, as shown in Figure 43 on page 128: 
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Name 


Addas: i»Par? Q Variable 

Add | Cancel | I Help I 


Figure 43. The Add Part Window 

2. Type the part’s class name in the Part class field. 

This is the class name that was specified when the part was created. When you 
begin typing, you replace the highlighted prompt with the name of the part you 
want to add. 

The asterisk at the end of the name is a reminder that you are actually entering a 
pointer to the part. When you enter a valid class name for the part without 
deleting the asterisk. Visual Builder automatically selects the Part radio button. 
You can change this by selecting the Variable radio button if you want to place 
a pointer to a variable on the free-form surface. Figure 44 shows how you could 
place a notebook part on the free-form surface using the Add Part window: 


[SI Add Part 


Part class INotebook* 


Name 

OAContractorViewi 

Add as: 

(j*Part O Variable 

r^n 

Cancel Help 


Figure 44. Placing a Notebook Part Using the Add Part Window 

If you delete the asterisk, the Part radio button is not available. This means that 
you can only place a variable on the free-form surface; Visual Builder 
automatically selects the Variable radio button indicating that you will be adding 
a variable whose type is the class name you entered in the Part class field, as 
shown in Figure 45 on page 129: 
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[SI Add Part 


Part class INotebook; 

Name OAContractorView 

Addas: QParl (^Variable 

| Add | Cancelj Help | 


Figure 45. Placing a Notebook Variable Using the Add Part Window 

Note: You cannot add abstract parts or template parts using the Add Part 

window. For example, IButton* is the abstract part that &IPushButton. 
inherits from. You can add &IPushButton., but not IButton*. 

Similarly, you cannot add an object factory part or a variable part using 
the Add Part window because they are templates. You must add them by 
selecting them on the parts palette. 

3. Type a name for the part in the Name field. 

This name will appear in the information area at the bottom of the Composition 
Editor when you select the part after it is placed; it is also used for the part when 
you generate your part code. 

The Name field is optional. If you leave it blank, the part’s class name is used. 

4. Select the Add push button to add the part. 

The Add Part window disappears and the mouse pointer turns into the same 
crosshairs used for placing a part on the free-form surface. 

Note: If you did not enter the name of a part that is known to Visual Builder in 
the Part class field, the Add push button is not enabled. 

5. Move the crosshairs to the place where you want to add the part and click mouse 
button 1. 

Guidelines for Placing Parts on the Free-form Surface 

Following are guidelines for placing parts on the free-form surface; 

• Avoid overlaying parts 

You can overlay visual parts. Generally speaking, however, it is not good 
interface design for one part to overlay another part, such as one push button 
either completely or partially covering another push button. Be aware that 
completely overlaying a part can cause focus problems, meaning that runtime 
users may be able to see, but not select, the part. 
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Partially overlaying a part can cause problems, too, because the runtime users 
might not be able to see where the overlaying occurs. When they try to select 
the part that is partially overlaid, they may be lucky and select the right spot, or 
they may select the part that is overlaying the part they are trying to select. If 
you overlay parts, be sure to do it in a way in which the user can understand why 
the parts are overlaid and how to select them. 

You cannot overlay, or cover up, nonvisual parts. You can overlay visual parts, 
but you should avoid doing this if possible unless you are placing parts on top of 
a part in the Composers category (see the next guideline). 

• Place other parts on top of parts in the Composers category 

Parts included in the Composers category have a special behavior; these parts can 
contain any other visual parts that are placed on top of them. The parts that the 
Composers part contains automatically become subparts of the Composers part. 
For example, if you place an entry field, a list box, and two push buttons in a 
frame window, the frame window contains the other parts and they, in turn, 
become the frame window’s subparts. 

The following table lists each of the Visual Builder categories and specifies how 
you can use the parts in each category. 


Figure 46. Categories and how you can use their parts 

Category 

Use Parts to Contain Other 
Parts? 

Use Parts as Subparts? 

Buttons 

No 

Yes 

Data entry 

No 

Yes 

Lists 

No 

Yes 

Frame Extensions 

No 

No 

Sliders 

No 

Yes 

Composers 

Yes 

Yes 

Models 

No 

No 

Other 

No 

No 


• Use supplementary composite parts as subparts 

Suppose you create a visual composite part that consists of a canvas on which 
you have placed other visual parts, such as radio buttons and check boxes, with 
each radio button and check box connected to a variable, as shown in the 
following figure: 
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Figure 47. Parts Connected to Variables 

Assume this part is not your main composite part but is instead a supplementary 
part that you want to use in your application’s user interface. When you place 
this part in your main composite part, such as in a frame window, as shown in 
the following figure, you place it and work with it as one part, not as a canvas 
and separate radio buttons and check boxes. The frame window contains the 
entire supplementary part, which becomes a subpart of the frame window. 


FrameWindow 


Q RadioButtonl 
Q RadioButton2 

□ CheckBoxI 

□ CheckBox2 


PushButtonl 


□ 


PushButton2 


Figure 48. Composite Part Placed in Frame Window as Subpart 
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One of the first things you have probably noticed is that the connections for a 
supplementary composite part are not displayed when that part is added to 
another part. The connections and variables are still there; you just cannot see 
them because you cannot edit them directly from the Composition Editor window 
that contains the main composite part. Also, you cannot select the individual 
radio buttons, check boxes, or their connections in the supplementary part that 
you placed in your main part. 

To change the connections or the default text on the radio buttons and check 
boxes, or to do anything else to alter this part, you must edit the part indirectly, 
as described in “Editing Parts Placed on the Free-form Surface” on page 153. 

Selecting and Deselecting Parts 

Before you can perform an action on a part that you have placed on the free-form 
surface, such as sizing it, you must first select the part. The name of the part 
currently selected is displayed in the information area at the bottom of the 
Composition Editor. If more than one part is selected, then *Multiple selection* is 
displayed. 

You cannot select parts and connections together. They are mutually exclusive. 
However, if you delete a part that is connected to other parts. Visual Builder deletes 
the connections in addition to the part. 

When a part is selected, small boxes, called selection handles, are displayed on its 
corners. If more than one part is selected, the one you selected last has solid 
selection handles, indicating that it is the anchor part. The other selected parts have 
hollow selection handles as shown in the following figure: 



Figure 49. Multiple Parts Selected with the Entry Field as the Anchor Part 
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Some parts are not sizable and, therefore, do not have any selection handles. These 
parts have their background reverse colored. Parts with this behavior include 
variables, menus, and tear-off attributes, among others. 

The following sections describe how to select and deselect a single part and multiple 
parts. 

Selecting a single part 

To select a part that you have placed on the free-form surface, click on the part with 
mouse button 1. If other parts are already selected, they are deselected automatically. 

Selecting multiple parts 

Selecting multiple parts enables you to perform the same operation on several parts at 
once. To select multiple parts, do one of the following: 

• Hold down the Ctrl key and click mouse button 1 on each additional part you 
want to select. 

• Hold down mouse button 1 instead of clicking it; then move the mouse pointer 
over each additional part you want to select. After you select the parts, release 
mouse button 1. 

Note: Depending on the operation you want to perform, remember to consider which 
part you want to be the anchor part because that is the part you want to select 
last. For example, if you select two parts because you want to match the 
width of one part to the width of the other, the part you select last is the 
anchor part, the part whose width is used for the operation. 

Deselecting parts 

To deselect a part after you have selected it, do the following: 

1. Hold down the Ctrl key. 

2. Click on the selected part with mouse button 1. 

To deselect multiple parts, do the following: 

1. Hold down the Ctrl key. 

2. Click on a selected part with mouse button 1. 

3. Without releasing either the Ctrl key or mouse button 1, move the mouse pointer 
to another selected part. 

4. Repeat the previous step until all parts that you want to deselect have been 
deselected. 
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Manipulating Parts 

Once a part is added to the free-form surface, you can manipulate it in a number of 
different ways. The following sections explain each of those ways. 

Displaying Pop-up Menus 

To display the pop-up menu of a part, click on the part with mouse button 2. The 
pop-up menu displays the operations you can perform on that part. 

A part does not have to be selected for you to display its pop-up menu. The pop-up 
menu that is displayed is for the part the mouse pointer is over when mouse button 2 
is clicked, even if another part is selected. 


Copying Parts 

To copy parts by dragging them, do the following: 

1. Select all the parts you want to copy. 

If you only want to copy one part, you do not have to select it. 

2. Move the mouse pointer over the part you want to copy or one of the selected 
parts. 

3. Hold down the Ctrl key and mouse button 2. 

4. Drag a copy of the part or parts by moving the mouse pointer to a new position. 

An outline of the part or parts is displayed to help you with positioning. When 
you are copying multiple parts, the outlines of each part move together as a 
group. 

5. Release the Ctrl key and mouse button 2 when the part or parts are where you 
want them to be. 

A copy of the part or parts appears where you positioned the outline or outlines. 

Copying parts using the clipboard 

To copy parts by using the clipboard, do the following: 

1. Select all the parts you want to copy. 

2. From the Edit pull-down menu, select Copy. 

A copy of each selected part is placed on the clipboard. 

3. Select Paste from the Edit pull-down menu when you are ready to use the parts. 

The mouse pointer turns to crosshairs to show that it is loaded with the copied 
parts. 

4. Position the mouse pointer where you want the parts to be copied. 
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5. Click mouse button 1. 

Copies of the parts are pasted at the position of the mouse pointer. 

Parts that you copy remain on the clipboard until you copy something else. 
Therefore, you can continue to paste copies of those parts by selecting 
Paste, positioning the mouse pointer, and clicking mouse button 1. 

If you select Paste and then decide against pasting the parts, you can 
unload the mouse pointer by either selecting the Selection Tool on the tool 
bar or by selecting Tools-^Selection Tool on the menu bar. 


Deleting Parts 

To delete one or more parts, do the following: 

1. Select all of the parts you want to delete. 

If you are deleting just one part, you do not have to select it. 

2. Position the mouse pointer over the part you want to delete or one of the selected 
parts. 

3. Click mouse button 2. 

4. From the part pop-up menu, select Delete. 

The part or parts are deleted. 


O 


Any connections between the part that you are deleting and other parts are 
also deleted. Visual Builder displays a message to alert you to this. 
However, the Edit-^Undo function also restores any connections that were 
removed when you deleted the part. 


Editing Text Strings 

Some visual parts, such as push buttons and menus, have text strings. To directly 
edit a part’s text string, do the following: 

1. Hold down the Alt key. 

2. Click mouse button 1 on the text string. 

3. Edit the text string. 

4. When you have finished, do either of the following: 

• Click mouse button 1 anywhere outside of the text string. 

• Press Shift+Enter. 
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You can also use this direct editing technique to edit the names of 
nonvisual parts. The name of a nonvisual part is displayed directly below 
its icon. 


Renaming Parts On the Free-form Surface 

When you use parts in the Composition Editor, Visual Builder gives those parts a 
name based on the names given to the parts on the parts palette or the names you 
specify when you place parts on the free-form surface. For example, the first push 
button part that you use is named PushButtonl. When you select this part, the 
information area at the bottom of the Composition Editor shows the message 
“PushButtonl selected.” The second push button you use is named PushButton2, the 
third is named PushButton3, and so forth. These default names are assigned to help 
Visual Builder distinguish one part from another, as well as the connections between 
parts, when you generate the code to build your application. 

If you want to give parts names that are more descriptive or meaningful to your 
application, you can do so as follows: 

1. Move the mouse pointer over the part whose name you want to change. 

2. Click mouse button 2 to display the pop-up menu for the part. 

3. Select Change Name. 

A Name Change Request window is displayed. The following figure shows a 
Name Change Request window for a push button part. 



Figure 50. Name Change Request Window for a Push Button Part 

4. Type a new name in the entry field. 

5. Select OK. 

Visual Builder changes the name of the part to the name that you typed in the 
entry field. 
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You can also change a part’s name by opening the part’s settings notebook and 
changing the name in the Subpart name field. 

Arranging Parts 

You can arrange parts on the free-form surface in a number of different ways. The 
following sections explain each of those ways. 


Moving Parts 

To move a part, move the mouse pointer over the part, hold down mouse button 2, 
and move the mouse pointer to drag the part to the new position. 


e 


You can move several parts at once by first selecting all the parts you want 
to move and then dragging one of the parts as described. All of the 
selected parts will move together, maintaining their position relative to each 
other. 


Positioning parts on the grid 

The free-form surface has a grid that you can use to position parts. In addition, parts 
that can contain other parts (any Composers part, such as a frame window) have a 
grid associated with them. You can use this grid to align and evenly space subparts 
that Composers parts contain. 


To position the top-left corner of parts to the nearest grid coordinate, do the 
following: 

1. Select all the parts you want to position to the grid. 

Note: If the parts you select are subparts, they are positioned to the grid set up 
inside the Composers part, not the grid for the free-form surface. 


O 


2. Select 



, the Snap To Grid tool. 


You can automatically position a part to the nearest grid coordinate when it 
is added to the free-form surface or a Composers part by selecting Snap On 
Drop from the Options pull-down menu. 


Chapter 8. Learning to Use Parts 137 











Developing Applications 


Specifying Grid Spacing 

To specify the grid spacing, do the following: 

1. From the pop-up menu of the Composers part or the free-form surface, select Set 

Grid Spacing. 

2. Specify the horizontal and vertical distance between the lines of the grid in 
pixels. 


Showing and Hiding the Grid 

To toggle between showing and hiding the grid for the free-form surface, do one of 
the following: 


• If no parts are selected, you can select 
the grid for the free-form surface. 


, the Toggle Grid tool to toggle 


• If a Composers part is selected, selecting the Toggle Grid tool toggles the grid 
for the Composers part instead of the free-form surface. 


Toggling between showing and hiding the arid for a Composers part 


To toggle between showing and hiding the grid for a Composers part, do one of the 
following: 


• Select the Composers part and the select 


, the Toggle Grid tool. 


• From the Composers part’s pop-up menu, select Toggle Grid. 


Sizing Parts 

To change the size of a part, select it and use mouse button 1 to drag one of the 
selection handles to the new position. An outline of the part is displayed under the 
mouse pointer to show you the new size of the part. 
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You can size several parts at once by first selecting all the parts you want 
to size. 

To size a part in only one direction, press and hold the Shift key while 
using mouse button 1 to size the part. Holding down the Shift key 
prevents one dimension of the part from changing while you resize the 
other dimension. For example, to change the width of a part but prevent its 
height from changing, hold down the Shift key while changing the width. 

You can also size a part to the grid coordinates by selecting Snap On Size 
from the Options pull-down menu. 


Matching Part Sizes 

To size parts to the same width or height of another part, do the following: 

1. Select all the parts you want to size, making sure the last part you select is the 
part whose size you want the others to match. 

2. Select one of the following sizing tools from the tool bar: 


Match Height 

The size of all the parts you selected, with the exception of the last part, changes 
to match the size of the last part selected. 


Match Width 


Aligning Parts 

To align parts to the same position of another part, do the following: 

1. Select all the parts you want to align, and then select the part you want the others 
to be aligned with. 

2. Select one of the following alignment tools from the tool bar: 


• F!7%1 

j r^i 

Align Left 

l|i 

Align Top 

EZX3 

cp 

Align Center 

lj|i 

Align Middle 

r~i S 

|gg| ! 

Align Right 

ill 

Align Bottom 
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Spacing Subparts Within Composers Parts 

To evenly space subparts within their Composers part, do the following: 

1. Select all the parts you want to evenly space. 

2. Select one the following spacing tools from the tool bar: 

□ On 

1 1 1 Distribute Horizontally 



Distribute Vertically 


Spacing Parts Within a Bounding Box 

To evenly space parts within the unseen bounding box that contains the selected parts, 
do the following: 

1. Select all the parts you want to evenly space. You must select a minimum of 
three parts. 

2. From the pop-up menu of one of the selected parts, select Layout^Distribute, 
and then one of the following: 

Horizontally In Bounding Box 

Evenly distributes the selected parts within the region bounded by the leftmost 
edge and rightmost edge of the selected parts. 

Vertically In Bounding Box 

Evenly distributes the selected parts within the region bounded by the topmost 
edge and bottommost edge of the selected parts. 


For more information on tool bar tools, see “The Tool Bar” on page 43. 


Changing Settings for a Part 

The settings notebook of a part provides a way to display and set attributes and 
options for the part. 

Opening the settings notebook for one part 


To open the settings notebook for a part, move the mouse pointer over the part and 
do one of the following: 

• Double-click mouse button 1. 

• Click mouse button 2 and select Open settings from the part’s pop-up menu. 
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Opening settings notebooks for multiple parts 

You can open the settings notebooks for multiple parts by doing the following: 

1. Select the parts whose settings you want to change. 

2. Move the mouse pointer over one of the selected parts. 

3. Click mouse button 2. 

4. Select Open settings from the pop-up menu. 

Visual Builder opens a settings notebook for each of the selected parts. 

Navigating through a settings notebook 

You can navigate through the notebook pages in the following ways: 

• To turn the pages of a notebook, use the small left- and right-arrow push buttons 
at the bottom right corner of each page. 

• To move to a different settings category, select one of the tabs to the right of the 
pages. 

Note: When a category has more than one page, the page number and total 

number of pages within the category are displayed at the bottom of the 
page. 

• If all the category tabs cannot fit below the pages of the notebook, small double 
left- and right-arrow push buttons are displayed to the left and right of the 
category tabs. Use these buttons to move through the available category tabs. 

About the settings pages 

The following list contains a description of each of the pages a settings notebook may 
contain: 

General 

A page for setting the name of the part, any static text that may appear on the part, 
and other part-specific settings. For example, the General page for an IMenuItem* 
part contains a group box for setting the keyboard accelerator for the menu item. 
Refer to the Visual Builder Parts Reference for descriptions of specific settings for 
parts. 

Control 

A page that allows you to specify information for the part in its role as an OS/2 
control, such as fly over text, a window ID, and whether the part is available for 
the user to select. 

Styles 

A page that provides style settings from the IBM Open Class Library. The style 
settings generally correspond to those of the class on which the part is based. 
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Refer to the IBM Open Class Library Reference for descriptions of the style 
settings. 

Selecting the defaultStyle check box means you want Visual Builder to use the 
default style provided for the class by the IBM Open Class Library. You can 
select this check box and then modify the default settings by selecting the On and 
Off radio buttons on the page beside each style setting. Doing this means you 
want Visual Builder to use the default style except for any exceptions that you 
have made by turning style settings on or off. 

The Default column shows which style settings are the defaults as specified for the 
class in the IBM Open Class Library. Visual Builder has not turned these style bits 
on or off. They are set to whatever the default settings are supposed to be. 

If you deselect the defaultStyle check box and also turn off one or more of 
the required settings, you will get errors when you generate and compile 
your code. However, selecting this check box ensures that no required 
settings will be omitted. Therefore, we recommend that you keep the 
defaultStyle check box selected so that you always have the required 
settings. 

Selecting one style setting does not cause another to be automatically 
deselected. For example, selecting minor tabs for a notebook page does not 
cause major tabs to be deselected. In this case, the major tab style setting 
overrides the minor tab setting. Be sure to deselect the styles that you do 
not want to use. 


Handlers 

A page that allows you to list handlers that you want to attach to this part. You 

can use handlers instead of event connections, such as event-to-action connections. 

List the handlers in the order in which they should be called. 

Adding a handler 

To add a handler, do the following: 

1. Enter the name of the handler class in the Handler Name field, along with the 
list of parameters that you want to send to the handler’s constructor. If you 
use any part names as parameters, be sure to use the default name that Visual 
Builder has assigned unless you have changed the name. Also, put a lower 
case “i” before those parameters because Visual Builder prefixes the part name 
with an “i” when it generates the code files. For example, if you are using the 
first entry field that you placed in a frame window as a parameter and have not 
changed the default name that Visual Builder assigns, the parameter name 
would be iEntryField 1. 
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2. If the Handler List list box contains other handlers, select the handler that you 
want your new handler to either precede or follow. 

3. Select either the Add after or Add before push button. 

If you did not import the handler class from a .vbe file. Visual Builder displays 
a message saying that the name you entered is not a valid part and asks if you 
want to continue. 

4. Select the Yes push button. 

The message disappears and the handler is added either after or before the 
handler that is selected in the Handler List list box, depending on which push 
button you select. 

5. Select the OK push button to save the new handler in the handler list and 
close the settings notebook. 

We recommend that you put your handler class declaration and code in 
separate user .hpv and .cpv files rather than modifying the files that Visual 
Builder generates. This way, if you need to regenerate the files, you do not 
have to recreate your handler code. 

Be sure to include the names of the files that contain the handler code in 
the User .hpv file and User .cpv file fields in the Class Editor. 

For information about implementing handlers, refer to the IBM Open Class 
Library User’s Guide and the IBM Open Class Library Reference. 


Moving a handler 

To move a handler to a different position in the list, do the following: 

1. Select the handler that you want to move. 

2. Select the Move push button. 

3. In the dialog that is displayed, select the handler that is to precede or follow 
the handler being moved. 

4. Select the Move after push button to move the handler after the selected 
handler, or select the Move before push button to move the handler before the 
selected handler. 

The dialog disappears and the handler is moved. 

Removing a handler 

To remove a handler from the list, do the following: 

1. Select the handler you want to remove from the list. 

2. Select the Remove push button. 
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The selected handler is removed from the list. 

Color 

A page that allows you to change the color of the part. 

To change the color, do the following: 

1. In the Color Area group box, select the area, such as foreground or 
background, whose color you want to change. 

2. Do one of the following: 

• If you want to specify red-green-blue values, select the RGB check box 
and specify values in the fields in the RGB Values group box. 

• If you want to select a color by its name, deselect the RGB check box and 
select a color from the Colors drop-down list box. 

3. Select either the Apply push button to see how this color looks for your part 
without saving the change or the OK push button to close the settings 
notebook and save the color change. 

Size/Position 

A page that allows you to specify the size and position of a part. 

To specify the size and position of a part, do the following: 

1. In the x and y fields, specify the initial x/y coordinates for the part. These 
coordinates determine the position of the part’s upper left corner. 

2. In the width and height fields, specify the number of pixels for the width and 
height of the part. 

3. Optionally, you can also specify the smallest size the part can have by using 
the Minimum Size group box to do either of the following: 

• If you want the minimum size to be calculated for you, select the 

Calculate at execution time radio button. 

• If you want to specify the minimum size for the part, select the Set value 
here radio button and then enter the width and height in pixels in the 
corresponding fields. 

Font 

A page that allows you to specify the font that is to be used for the part. 

To change the font for a part, do one of the following: 

• If you know the name and size of the font you want to use, you can enter them 
in their respective fields. 

• If you do not know the name and size of the font you want to use or if you 
want to change the style or emphasis, select the Edit push button. Visual 
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Builder displays a standard font dialog on which you can select the name, size, 
style, and emphasis you want to use for the part’s font. 

Using code strings to supply initial field values 

Many settings pages provide fields in which you can specify initial values for part 
settings. For example, the General page of the IEntryField* settings notebook 
contains a Text field and a Limit field. In the Text field, you can enter a text string 
that you want Visual Builder to initially display in the entry field. The Limit field 
contains a default value of 32, which represents the maximum number of characters a 
user can type in the entry field, and you can change this number. 

To facilitate National Language Support (NLS) translation and code changes in 
providing settings values, such as the ones just described, you can enter a code string 
to provide those values. You must precede the code string with a number sign (#). 

If the first character of your code string is a #, be sure to enter two #s—the first one 
to signify that a code string follows and the second one to begin your code string. 

For example, suppose you want the initial text in an entry field to be Enter a name 
here. Further, suppose that you want the limit for this entry field to be 18 characters. 
In a user header file (.hpv or .h), you could insert the following #define statements: 

fdefine NAME_PROMPT "Enter a name here" 
fdefine NAME_LENGTH 18 

Be sure to enter the name of the file that contains these #define statements 
in the Required include files field in the Class Editor. Otherwise, this file 
is not included when you generate the code for this part. 

Then, on the General page of the IEntryField* settings notebook you could enter the 
following in the Text and Limit fields, respectively: 

#NAME_PROMPT 

#NAME_LENGTH 

By doing this, the values that you defined for NAME_PROMPT and 
NAME_LENGTH are used when you generate the source code for the part being 
edited. 

For an example that uses a code string to specify an icon to represent items in a 
container, see the subsection titled “Specifying the container type and layout” in 
“Adding Container Parts” on page 235. 
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Activating settings changes 

After you make changes to the settings, you can activate them in the following ways: 

• Select the OK push button to immediately activate and save the settings changes 
you have made, and close the settings notebook. 

• Select the Apply push button to apply the settings changes you have made and 
keep the settings notebook open. 

This allows you to see whether you need to modify any of the changes you have 
made. The changes remain applied until you change them again. 

Select the Cancel push button to remove the settings notebook. If you made changes 
and selected the Apply push button, the changes are saved. 

Select the Help push button for more help with using the settings notebook. 

For information about the settings of a particular part, refer to the settings section of 
the part in the Visual Builder Parts Reference. 

Using the Generic Settings Notebook 

When you create a part. Visual Builder provides a settings notebook for that part. 

The settings notebook for your part has one page, which contains the following types 
of settings: 

• An entry field for each attribute that has a set member function 

The #define statements are supported for the generic settings notebook, just as 
they are for a regular settings notebook. See “Changing Settings for a Part” on 
page 140 for information about using #define statements in a settings notebook. 

• A check box for each Boolean attribute 

If your part has no attributes, the page displays a message saying that there are no 
values to set. 

To view the settings notebook for your part, do one of the following: 

• To set values for an instance of your part that you are using in a composite part, 
do the following: 

1. Place the part in the Composition Editor. 

2. Move the mouse pointer over the part and click mouse button 2. 

3. Select Open settings from the pop-up menu. 

Visual Builder displays the settings notebook for the part. 
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• To set attribute values for your part that will be available each time your part is 
used, do the following: 

1. Open the part. 

2. If the part is a nonvisual or class interface part, switch to the Composition 
Editor. You will already be in the Composition Editor if your part is a 
visual part. 

3. Move the mouse pointer over the free-form surface and click mouse 
button 2. 

4. Select Open settings from the pop-up menu. 

A quicker way to open the generic settings notebook is to double-click on 
the part. 

Visual Builder displays the settings notebook for the part. 

The following figure shows the generic settings notebook for the OAContract part: 



Figure 51. Generic Settings Notebook for OAContract Part 


The notebook page includes settings for attributes that your part inherits from other 
parts in addition to attributes for the part you created. For example, the 
enabledForNotification check box is present because the OAContract part inherits 
this Boolean attribute from IStandardNotifier. 
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Setting the Tabbing Order 

The tabbing order specifies the order that the input focus moves from part to part as 
the user presses the Tab key. The tabbing order can further specify the order that the 
input focus moves to parts within a tab group as the user presses the arrow keys. 

The tabbing order can only be set or displayed for parts that are placed within a 
Composers part. For example, if you place a row of push buttons in a frame window, 
you can set the tabbing order for the push buttons. 

The initial order of the parts in the tabbing order list is determined by the order in 
which you place the parts on the Composers part. Also, the first part in the list is the 
part that receives the initial input focus. For example, if the first part in the list is a 
push button, that push button receives the initial input focus when the application 
starts. 

Displaying the tabbing order list 

To display the tabbing order list, do the following: 

1. Move the mouse pointer to the Composers part whose tab order you want to 
change. 

2. Click mouse button 2. 

Visual Builder displays the pop-up menu for the Composers part. 

3. Select Tabbing And Depth Order. 

A list of the current tabbing order is displayed. Figure 52 on page 149 shows 
the tabbing order list for a canvas part that contains three push buttons: 
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Group 



Figure 52. Sample Tabbing Order List 

When the tabbing order is displayed, you can do the following: 

• Change the positions of parts in the tabbing order list. 

• Set groups and tab stops. 

• Perform operations on parts in the tabbing order list. 

Changing the Positions of Parts in the Tabbing Order List 

Since the order in which parts are placed on a Composers part determines the tabbing 
order, you will probably need to change the order of the list as you add or rearrange 
parts. For example, suppose you decide to rearrange the three push buttons from the 
example in the preceding section so that PushButton3 is between PushButtonl and 
PushButton2, as shown in Figure 53. 


PushButtonl PushButton3 PushButton2 


Figure 53. Push Buttons Placed Out of Sequence 

As shown in Figure 52, the tabbing order of these push buttons is PushButtonl, 
PushButton2, PushButton3, even though PushButton3 is now between PushButtonl 
and PushButton2. 
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By moving PushButton3 between PushButtonl and PushButton2 in the tabbing order 
list, you can change the order so that you can cursor directly from PushButtonl to 
PushButton3 instead of jumping over to PushButton 2 first. The changed tabbing 
order list is shown in Figure 54 on page 150. 



Figure 54. Tab Order List for Push Buttons Changed 


To change the position of a part within the tabbing order list, do the following: 

1. Move the mouse pointer to the part whose position you want to change. 

2. Press and hold mouse button 2. 

3. Drag the part to a new position in the list. 

4. Release mouse button 2. 


O 


You can change the position of several parts within the tabbing order at the 
same time by first selecting all the parts you want to move. You select 
multiple parts by holding down the Ctrl key and clicking on the parts with 
mouse button 1. 

You cannot move a subpart to a new Composers part by changing the 
tabbing order. You must do this in the Composition Editor. 
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Setting Groups and Tab Stops 

If you want the user to be able to move the input focus to a part using the Tab and 
Backtab keys, select the Tab stop check box to the left of the part in the tabbing 
order list. 

If you want the user to be able to move the input focus to a part with the keyboard 
arrow keys, select the Group check box to the left of the first part in the group. All 
other parts listed below the part that has Group selected are included in the group. 

To start another group, select the Group check box for the part that you want to be 
the first part in that group. If a part has both Group and Tab stop selected, a user 
can tab to the first part in the group and then use the arrow keys to move to the other 
parts in the group. 

Special considerations for radio buttons and entry fields 

When you put radio buttons in groups, they become mutually exclusive within their 
group. For example, suppose you have four consecutive radio buttons in your list and 
you select the Group check box for RadioButtonl and RadioButton3. In this case, 
RadioButtonl and RadioButton2 become mutually exclusive in their group, with 
RadioButton3 and RadioButton4 mutually exclusive in their group, as well. 

Figure 55 shows an example. Tab stops are also set so a user can tab between the 
two groups. 



Figure 55. Tab Order List for Radio Buttons 
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Consider setting a tab stop on each entry field that a user can type in to allow the 
user to move the input focus from one entry field to another. Read-only entry fields 
do not need a tab stop and arrow keys only move the cursor within an entry field; 
only the Tab key, the Backtab key, and the mouse can change the input focus from 
one entry field to another. 

Style uuidelines for setting groups and tab stops 

The following are some typical style guidelines for setting groups and tab stops: 

• The position of the parts in the tabbing order should be the same as the order in 
which they are displayed in the window, from left to right and then top to 
bottom. 

• Parts that are not in groups, such as entry fields and list boxes, should have 

Group and Tab stop selected. 

• Each group of related parts, such as check boxes and radio buttons, should be put 
within an outline box or a group box. 

If there is only one group of related parts, such as push buttons, you do not need 
to put them within an outline box or group box. Select only Tab stop for these 
parts. 

• Parts that should not receive input focus, such as static text parts, should not have 
either Group or Tab stop selected. 

Performing Operations on Parts in the Tabbing Order List 

You can perform many of the same operations on parts listed in the tabbing order that 
you can perform on the parts on the free-form surface. Visual Builder provides 
pop-up menus that contain the allowable operations for each part in the list. 

Examples of typical operations are opening a part’s settings, editing a part, and 
browsing a part’s features. 

To perform an operation on a part in the tabbing order list, do the following: 

1. Move the mouse pointer over the part. 

2. Click mouse button 2. 

Visual Builder displays the pop-up menu for the part. 

3. Select the operation you want to perform. 
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Editing Parts Placed on the Free-form Surface 

Suppose you create a composite part, add it to another composite part that you are 
creating, and then realize that you need to change the first composite part. With 
Visual Builder you do not have to start over. It provides a way for you to edit the 
part that needs to be changed right from the free-form surface. 

The only exception is the base parts that Visual Builder provides. Visual Builder 
does not allow you to modify these parts. This includes all of the parts that the 
vbbase.vbb file contains. If you place one of these base parts on either a Composers 
part or the free-form surface, you can modify the subpart by doing any of the 
following: 

• If you want to add an action to the subpart, consider connecting to a member 
function or custom logic that belongs to the composite part, instead. Write a 
member function or provide custom logic if you need to perform an action of 
limited usefulness, that is, one that you do not anticipate using very often, and 
that you do not want derived parts to inherit. For information about using 
member functions and custom logic in connections, see the following: 

- “Adding an Event-to-Member Function Connection” on page 184 

- “Connecting Features to Custom Logic” on page 188 

• If you want to add a new feature that you plan to use often, create a new part 
that is derived from the base part. For example, to add a new feature to an 
IEntryField* part, create a new visual part whose base part is the IEntryField* 
part and replace the IEntryField* part that you were using with your new part. 
You can then add as many new features to your new part as you need. 

• If you derive a new part from a base part, you also have the option of adding 
handlers to the new part. One reason for adding handlers is that you might want 
to monitor Presentation Manager messages to see when certain events occur and 
then notify observers. Another reason is that you might want to add special 
behavior to your part. You can add handlers to parts that Visual Builder 
provides on the Handlers page of the part’s settings notebook. For more 
information about handlers, refer to the IBM Open Class Library User’s Guide. 

If you need to edit a part that was added to the part you are currently editing, do the 
following: 

1. If you have not already done so, load the .vbb file that contains the part you want 
to edit. 

Note: See “Loading Part Files” on page 33 if you need information about 
loading .vbb files. 

2. Move the mouse pointer over the part you want to edit. 
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3. Click mouse button 2. 

The part’s pop-up menu appears. 

4. Select Edit Part. 

Visual Builder displays the appropriate editor for the part, as follows: 

• If you are editing a visual part. Visual Builder displays the Composition 
Editor 

• If you are editing a nonvisual or class interface part. Visual Builder displays 
the Part Interface Editor. 

5. Edit the part. 

If you want to promote any of the features of the parts used to create the 
composite part you are editing, doing so now keeps you from having to edit 
this part again later. See “Promoting a Part’s Features” on page 155 if you 
need more information about doing this. 


6. Select File-^Save to save the part. 

7. Close the editor by doing one of the following: 

• Double-click on the system menu icon. 

• Select File^Exit. 

The editor you are using disappears and you are returned to the Composition 
Editor you were using previously. However, Visual Builder has not applied the 
changes you made to the part you just edited, so those changes are not visible 
yet. 

8. Select File^Save to save the original part. 

9. Close the Composition Editor for the original part that you were editing, as 
described above. 

10. Reopen the original part you were editing by double-clicking on the part’s name 
in the Visual Builder window. 

You should now be able to see the changes you made to the part that you edited. 
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Promoting a Part’s Features 

In “Guidelines for Placing Parts on the Free-form Surface” on page 129, we 
explained the relationship between parts in the Composers category and parts that are 
placed on top of them, called subparts. When you create a visual part that consists of 
a part from the Composers category that contains subparts, you can then place that 
visual part on top of another part from the Composers category. However, if you do 
this, the features of the subparts in the visual part that you created are not 
automatically available. You must promote these features to use them in connections. 

For example, suppose you create a visual part called Buttons whose base class is 
ICanvas*. This part consists of a canvas part that contains three push button parts. 
Here is what the Buttons part looks like: 


OK 


Cancel 


Help 


Figure 56. Buttons Part 

Suppose you create another visual part whose base class is IFrameWindow* and then 
add the Buttons part to the frame window part. Here is what the frame window part 
with the Buttons part looks like: 


FrameWindow 


□ 


OK 


Cancel 


Help 


Figure 57. Frame Window with Buttons Part 


Now, suppose that you want to connect the buttonClickEvent feature of the Cancel 
push button to the close feature of the Frame Window so that the window closes 
whenever the Cancel push button is selected. However, features of the push button 
parts are not automatically available for connections because the push buttons are 
subparts of the canvas. 

When you use a part such as Buttons as a subpart, only the features of the Buttons 
part’s ancestor parts (ICanvas, IWindow, and so forth) are available in the 
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connections menu for the Buttons part. To use the features of the push button parts, 
you must promote them to the Buttons part. You can do this either before or after 
you add the Buttons part to the frame window. 

The following steps show you how to promote a part’s features from the Composition 
Editor. 


O 

1. If you have not already done so, load the .vbb file that contains the composite 
part whose features you want to promote. 

Note: See “Loading Part Files” on page 33 if you need information about 
loading .vbb files. 

2. If you have not already done so, open the composite part or edit the subpart, 
whichever is necessary. 

Note: See the following if you need more information: 

• “Editing Parts Placed on the Free-form Surface” on page 153 for 
information about editing subparts after you have placed them on the 
free-form surface. 

• “Opening Parts” on page 121 for information about opening parts 

Visual Builder displays the Composition Editor with the part that you are opening 
or the subpart that you are editing on the free-form surface. 

3. Move the mouse pointer over a part whose features you want to promote. 

4. Click mouse button 2 to display the part’s pop-up menu. 

5. Select Promote Part Feature. 

Visual Builder displays a window with three columns of features: one for 
attributes, one for events, and one for actions. The following figure shows the 
window that is displayed for a push button part. 


To promote features of several subparts, we recommend using Promote 
page of the Part Interface Editor. For information about promoting a part’s 
features from the Part Interface Editor, see “The Promote Page” on 
page 73. 
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Promote features from: 


action 

applyBidiSettings 

capturePointer 

click 

convertToGUIStyle 

disable 

disableDefault 

disableGroup 

disableHelp 

■■n 


attribute 

activeColor 

allowsMouseClickFocus 

asDebuglnfo 

asString 

autoDeleteObject 
autoDestroy Window 
backgroundColor 
bidiSupported 

> 


event 

buttonClickEvent 

commandEvent 

gotFocusEvent 

inputDisabledEvent 

inputEnabledEvent 

lostFocusEvent 

systemCommandEvent 

visibilityDisabledEvent ^ 


□ 


Promote feature name 
Previously promoted 


Promote 


Remove 


Help 


Figure 58. Promoting Features for a Push Button Part 


6. Select a feature. 

The name of the feature you selected is displayed in the Promote feature name 
entry field prefixed with the name of the part. This is done so that when you 
make the connection, you can tell which push button part the feature belongs to. 
For example, if you selected the buttonClickEvent feature for the PushButton2 
part, the feature name displayed in the entry field would be 
pushButton2ButtonCl ickEvent, as shown in the following figure. This is how the 
feature name will appear in the connections menu unless you change it before 
performing the next step. 
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Promote features from: PushButton2 


action attribute event 


applyBidiSettings 


activeColor 
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capturePointer 


allowsMouseClickFocus 

commandEvent 

click 


asDebuglnfo 

gotFocusEvent 

convertToGUIStyle 


asString 

inputDisabledEvent 
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inputEnabledEvent 

disableDefault 
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■ 
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> 
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Promote feature name P ushButton2ButtonClickEvent 
Previously promoted 


Promote 

Remove 


Help 


Figure 59. Part Name Prefixed to Feature Name for Promotion 

1 . Select the Promote push button. 

The feature name is added to the Previously promoted list box, as shown in 
Figure 60 on page 159. 
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Promote features from: PushButton2 
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Help 


Figure 60. Promoted Feature Added to Previously Promoted List 

8. Repeat the previous two steps until you have promoted all of the features you 
need to make the necessary connections. 

9. Close the window for promoting features. 

10. Select File^HSave to save the features you just promoted. 

11. Close the Composition Editor. 

You can now use the feature or features that you promoted to make connections. 

Tearing Off an Attribute 

Select Tear-Off Attribute from a part’s pop-up menu to work with an attribute as if 
it were a standalone part. The torn-off attribute is not actually a separate part but a 
variable that either represents the attribute itself or points to it. 

When you select Tear-Off Attribute, Visual Builder displays the list of attributes for 
the part that you are tearing from. After you select an attribute from the list, you can 
drop the torn-off attribute on the free-form surface. Visual Builder creates an 
attribute-to-attribute connection between the original part and the torn-off attribute. 
You can then make other connections to or from the torn-off attribute. See 
Chapter 9, “Learning to Use Connections” on page 167 if you need information 
about attribute-to-attribute connections. 
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You might want to tear off an attribute to do the following: 

• Allow direct access from one that is nested inside of another 

• Enable direct access to an attribute’s events and actions 

For example, in an address book application you might tear off attributes as follows: 

• You might have a Person part that contains both homeAddress and workAddress 
attributes, both of which, in turn, could contain street, city, and state attributes. 

• By tearing off either the homeAddress or workAddress attribute, you can create a 
new part that contains street, city, and state attributes. 

• Tearing off a homeAddress or workAddress attribute makes the nested street, city, 
and state attributes directly accessible. Now that the nested attributes are directly 
accessible, you can make connections to and from them, as well as to their 
associated events and actions. 


Undoing and Redoing Changes in the Composition Editor 

If you change something in the Composition Editor and then decide that you should 
have left things as they were, select Undo from the Edit pull-down menu to restore 
the part to its previous state. You can undo as many operations as you want, all the 
way back to when you opened the Composition Editor. 

If you undo an operation and then decide that you did the right thing in the first 
place, select Redo from the Edit pull-down menu. Redo restores the part to the state 
it was in before the last Undo, including any connections that were deleted. 

If you are not sure which operations you want to undo or redo, select Undo/Redo list 
from the Edit pull-down menu to display two lists of operations, one for undoing and 
one for redoing. From these lists, you can select an operation and then select the 
Undo or Redo push button. The operation that you select and all of the operations 
listed below it are undone or redone. 

Note: Undo, Redo, and Undo/Redo list only affect operations you perform on the 
free-form surface and parts palette in the Composition Editor. They have no 
affect on any of the functions in the File pull-down menu, such as Save, Save 
As, and Save and Generate, which you cannot undo. 
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Constructing a GUI: the OASearch Application 

The remainder of this chapter describes how to visually construct the graphical user 
interface (GUI) of an application using the OASearch application as an example. 

You construct a GUI by adding visual parts, such as push buttons, lists, and menus, 
to a window part. For a list of the visual parts available on the Composition Editor, 
see “The Parts Palette” on page 46. 

Adding Basic Visual Parts 

The purpose of this section is to guide you through constructing a version of the 
Opportunities Abound Contract Information window for the OASearch sample 
application. You construct this part (ContractView) in the Composition Editor using 
the basic visual parts. When finished, the Opportunities Abound Contract Information 
window looks like Figure 61. 


Opportunities Abound Contract Information 


□ 


Account Number 
Company Name 
Project Manager 
Department 

-Position Details 
Title 

Start Date 
Contractor 


Refresh 


Save 


End Date 


Clear 


Cancel 


Figure 61. Completed ContractView Window 


Adding the Parts 

Before starting this new visual part, make sure that oanonvis.vbb is loaded into Visual 
Builder. 

Adding the parts 

1. Because you are constructing a new user interface, begin by creating a visual 
part. Call it ContractView. 
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When you create a visual part, the Composition Editor opens a part that inherits 
from IFrameWindow*. By default, the client area of the IFrameWindow* 
appears as a canvas. 

2. Change the title of the window. 

3. Add the following parts to the window part: 

• Static text and entry field parts for Account Number, Company Name, 

Project Manager, and Department. 

• A group-box part for the Position Details group. Resize the group box. 

• Static-text and entry-field parts for the items inside the group box. 

• Push-button parts. 

See Figure 61 on page 161 to see how the window should look after the parts 
are added. 

Changing the Labels 

Directly edit the static text so that the text matches Figure 61 on page 161. 

Arranging the Parts 

Arrange the parts on the frame window part so they are aligned and positioned as 
shown in Figure 61 on page 161. 

For more information on how to perform these operations, see “Working with Parts 
on the Free-form Surface” on page 127. 

Changing the Settings 

Now that the parts have been added for the user interface, customize the parts by 
modifying their settings. 

Specifying a push button label with mnemonic 

On the General settings page for the middle push button, type 'Save in the Text 
field. Select the OK push button. 

The middle push button of your window now reads Save, with a mnemonic of S. 

This means the user can select the push button by pressing Alt+S. 

Repeat this procedure for the push button to the right of the Save push button, 
specifying Cl "ear as the push button label. This push button now reads Clear, with a 
mnemonic of E. 
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For the rightmost push button, specify 'Cancel as the label. This push button now 
reads Cancel, with a mnemonic of C. 

Specifying the default push button 

On the General settings page for the leftmost push button, type 'Refresh in the Text 
field. Select the Apply push button. The leftmost push button of your window now 
reads Refresh, with a mnemonic of R. 

On the Styles settings page, select the On radio button for the defaultButton style. 
Select the OK push button. The Refresh push button is now the default button for 
the window. This means the user can select the push button by pressing the Enter 
key. 

For details on the settings of a particular part, refer to the Visual Builder Parts 
Reference. For more information on how to perform these operations, see “Changing 
Settings for a Part” on page 140. 

Adding a Variable to a Composite Part 

Variables serve an important role in complex applications. Use variables instead of 
parts in the following situations: 

• To act as a placeholder inside a composite part for parts not found in the 
composite part. Using variables for nonvisual parts enables you to pass data or 
function between composite parts. 

• To represent part instances created with Object Factory parts. For more 
information on using Object Factory parts, see “Adding Visual Parts as Dynamic 
Instances” on page 266. 

Each variable must be set to the part type it represents. Once set, the variable takes 
on the interface of that part type. Unlike using a part, using a variable does not cause 
the part constructor to run. 

Begin by opening the ContractView part (found in contract.vbb) in the Composition 
Editor. If you prefer to use the OAContractView part, you can find this part in 
oawin.vbb. At this point, the ContractView part appears as shown in Figure 61 on 
page 161. 

We are using a variable instead of an OAContract* part because the contract data 
varies with the information entered from the OAQueryContract* part. 
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To add a variable to the free-form surface, select 



, the Models category. 


from the parts palette; then add L J , an IVBVariable* part, to the free-form 
surface. Change its name to Contract. The ContractView with a variable added 
appears as shown in Figure 62 on page 164. 


Opportunities Abound Contract Information 


□ 


Account Number 
Company Name 
Project Manager 
Department 

Position Details 
Title 

Start Date 
Contractor 


Refresh 


Save 


End Date 


Clear 


Cancel 


[B] 

Contract 


Figure 62. ContractView Window with Variable 


o 


Notice the square bracket symbols around the variable part. You can 
always identify a variable by these symbols. Also note that tear-off 
attributes also have square brackets and are in fact variables with a special 
connection. 


Changing the Variable’s Type 

When you add a variable part, its type is initially IStandardNotifier*, meaning that the 
variable can stand for any part. This variable is supposed to stand for an 
OAContract* in this example, so you must change its type. 

Note: You cannot use variables to represent template-based parts, such as 
IVSequence*. 

1. First, make sure the the .vbb file holding the OAContract part (oanonvis.vbb) is 
loaded into Visual Builder. 
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2. Select Change Type on the variable’s pop-up menu; then type OAContract* 

Adding the Variable to the Part Interface 

So far, the Contract variable is empty. To make the variable available for passing 
values from the main view (or any part outside ContractView), we must add the 
variable to the part interface of ContractView), Do this by selecting Promote Part 
Feature from the variable’s pop-up menu. See “Promoting a Part’s Features” on 
page 155 if you need information about doing this. 
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This chapter describes the types of connections that you can make and how to make 
them. Each connection description provides a definition of the connection, the color 
of the connection, whether the arrows are unidirectional or bidirectional, and whether 
the connection requires you to satisfy parameters to complete it. 

Attribute-to-attribute connection 


An attribute-to-attribute connection links two attribute values together. The purpose 
of this type of connection is to cause the value of one attribute to change when the 
value of another attribute changes. 

An attribute-to-attribute connection uses a bidirectional cyan arrow with the solid 
arrow head pointing to the target and the hollow arrow head pointing to the source. 
The bidirectional arrow indicates that a change in the value of either attribute can 
cause the value of the other attribute to change accordingly, except as noted in 
Figure 64 on page 168. When your part is created within an application, the target 
attribute is set to the value of the source attribute. Attribute-to-attribute connections 
never take any parameters. 

Note: You can use a class interface part as the source of a connection only when 
making an attribute-to-attribute connection. An attribute of a class interface 
part can be used to initialize an attribute of another part without using 
notification. 

In the following example, the text attribute of the entry field is connected to the 
accountNum attribute of the Contract. This connection causes the value of the 
accountNum attribute to change whenever the value of the text attribute changes, and 
vice versa. 


* — 

Contract 


Figure 63. Attribute-to-Attribute Connection 


The effect of attribute types on connections 

It is important to know the types of attributes that you are connecting. Otherwise, 
you might not achieve the results that you anticipate. 
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Figure 64 on page 168 shows the results of connecting attributes that have different 
behavior types. See “The Attribute Page” on page 58 for descriptions of the attribute 
types. 

Figure 64. Source and Target Considerations for Attribute Types 


If the source is a... 

And the target is 
a full attribute... 

And the target is 
a no-set 

attribute... 

And the target is a 
no-event attribute... 

full attribute 

All attribute 

behaviors are 

available to both 

the source and 
target attributes. 

The target attribute 
cannot set itself to 

the value of the 

source attribute. 

The target attribute 
cannot notify the 
source attribute when 
the target attribute’s 
value changes. 

no-set attribute 

The source 

attribute cannot set 

itself to the value 
of the target 
attribute. 

This is an invalid 

connection. 

The source attribute 

cannot set itself to 

the value of the 
target attribute; the 
target attribute cannot 
notify the source 
attribute when the 
target attribute’s 
value changes. 

no-event attribute 

The source 

attribute initializes 
the target attribute; 
no event 

notification occurs. 

The source 

attribute initializes 
the target attribute; 
no event 

notification occurs; 
the target attribute 
cannot set itself to 

the value of the 

source attribute. 

The source attribute 
initializes the target 
attribute; no event 
notification occurs; 
the target attribute 
cannot notify the 
source attribute when 
the target attribute’s 
value changes. 


Event-to-attribute connection 


An event-to-attribute connection allows the occurrence of the source event to change 
the value of the target attribute. To accomplish this, the connection calls the 
attribute’s set member function whenever the event occurs. If the attribute is a no-set 
attribute, you cannot make the connection. 

An event-to-attribute connection uses a unidirectional dark green arrow with the 
arrow head pointing to the target. If the attribute’s set member function requires data 
to satisfy its parameter, the connection line is initially dashed to show that it is 
incomplete unless event data is provided, causing it to turn solid. 
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You can satisfy the missing parameter value or override any event data that is present 
by connecting the parameter to an attribute, action, member function or custom logic, 
or by supplying a constant parameter value. See “Satisfying Parameters for 
Incomplete Connections” on page 179 for information about providing parameter 
values. 

In the following example, the buttonClickEvent feature of the Refresh push button is 
connected to the text attribute of the entry field. 

Refresh ► 


Figure 65. Event-to-Attribute Connection 


Event-to-action connection 


An event-to-action connection allows an action to start whenever the event that the 
action is connected to occurs. 

An event-to-action connection uses a unidirectional, dark green arrow with the arrow 
head pointing to the target. If the action requires data to satisfy its parameter, the 
connection line is initially dashed to show that it is incomplete unless event data is 
provided, causing it to turn solid. 

You can satisfy the missing parameter value or override any event data that is present 
by connecting the parameter to an attribute, action, member function or custom logic, 
or by supplying a constant parameter value. See “Satisfying Parameters for 
Incomplete Connections” on page 179 for information about providing parameter 
values. 

Also, the action that is the target of this connection can have a return value. If it 
does, you can treat the return value as a no-set attribute of the connection and use it 
as the source of another connection. The return value appears in the connection menu 
for the connection as actionResult. 

In the following example, the buttonClickEvent feature of the Add push button is 
connected to the addAsLast action of the multiline edit control. 



Figure 66. Event-to-Action Connection 
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Event-to-member function connection 


An event-to-member function connection calls a member function of the part 
currently being edited whenever the event that the member function is connected to 
occurs. 

An event-to-member function connection uses a unidirectional, light green arrow with 
the arrow head pointing to the target. If the member function requires data to satisfy 
its parameter, the connection line is initially dashed to show that it is incomplete 
unless event data is provided, causing it to turn solid. 

You can satisfy the missing parameter value or override any event data that is present 
by connecting the parameter to an attribute, action, member function or custom logic, 
or by supplying a constant parameter value. See “Satisfying Parameters for 
Incomplete Connections” on page 179 for information about providing parameter 
values. 

Also, the member function that is the target of this connection may have a return 
value. If it does, you can treat the return value as a no-set attribute of the connection 
and use it as the source of another connection. The return value appears in the 
connection menu for the connection as actionResult. 

In the following example, the buttonClickEvent feature of the Clear push button is 
connected to a resetFields member function. 



Refresh 

Save 

Clear 

Cancel 







Vital statistics 4-ilaK 


f 


Figure 67. Eveut-to-Member Function Connection 


Attribute-to-action connection 


An attribute-to-action connection allows an action to start whenever the event 
identification that is associated with the attribute is triggered. This connection is 
similar to an event-to-action connection because the connection calls the action 
whenever the attribute’s event is triggered. 
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An attribute-to-action connection uses a unidirectional, dark green arrow with the 
arrow head pointing to the target. If the action requires data to satisfy its parameter, 
the connection line is initially dashed to show that it is incomplete unless event data 
is provided, causing it to turn solid. 

The attribute’s value is passed as the first parameter of the action if no parameter is 
explicitly specified. You can satisfy any other missing parameter values or override 
the attribute value that is present by connecting the parameter to an attribute, action, 
member function or custom logic, or by supplying a constant parameter value. See 
“Satisfying Parameters for Incomplete Connections” on page 179 for information 
about providing parameter values. 

Also, the action that is the target of this connection can have a return value. If it 
does, you can treat the return value as a no-set attribute of the connection and use it 
as the source of another connection. The return value appears in the connection menu 
for the connection as actionResult. 

In the following example, the text attribute of the entry field is connected to the 
addAsLast action of the list box. 



Figure 68. Attribute-to-Action Connection 

Attribute-to-member function connection 


An attribute-to-member function connection allows a member function to start 
whenever the event identification that is associated with the attribute is triggered. 

This connection is similar to an event-to-member function connection because the 
connection calls the action whenever the attribute’s event is triggered. However, if 
the attribute is a no-event attribute, the member function is not signalled because a 
no-event attribute does not have an event identifier. 

An attribute-to-member function connection uses a unidirectional, light green arrow 
with the arrow head pointing to the target. If the member function requires data to 
satisfy its parameter, the connection line is initially dashed to show that it is 
incomplete unless event data is provided, causing it to turn solid. 

You can satisfy the missing parameter value or override any event data that is present 
by connecting the parameter to an attribute, action, member function or custom logic, 
or by supplying a constant parameter value. See “Satisfying Parameters for 
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Incomplete Connections” on page 179 for information about providing parameter 
values. 

Also, the member function that is the target of this connection can have a return 
value. If it does, you can treat the return value as a no-set attribute of the connection 
and use it as the source of another connection. The return value appears in the 
connection menu for the connection as actionResult. 

In the following example, a member function is called to calculate the presentation 
space in the list box. 



Figure 69. Attribute-to-Member Function Connection 

Custom logic connection 

A custom logic connection allows your customized logic to run whenever either of 
the following happens: 

• The value of the attribute that you connect it to changes. 

• The event that you connect it to occurs. 

If you connect an attribute to your custom logic, use the attribute’s event identifier to 
execute the custom logic when the attribute’s value changes. 

A custom logic connection uses a unidirectional, blue arrow with the arrow head 
pointing to the target. 

Also, the custom logic that is the target of this connection may have a return value. 

If it does, you can treat the return value as a no-set attribute attribute of the 
connection and use it as the source of another connection. The return value appears 
in the connection menu for the connection as actionResult. 

In the following example, custom logic is called to clear all of the entry fields in a 
notebook. Otherwise, you would need to make a separate connection from the push 
button’s buttonClickEvent feature to the clear action of each entry field. 
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Figure 70. Custom Logic Connection 


Parameter connections 


A parameter connection satisfies a parameter of an action or member function by 
passing either an attribute’s value or the return value from an action, member 
function, or custom logic. This connection looks similar to an attribute-to-attribute 
connection; it uses a bidirectional arrow, with the solid arrow pointing to the target 
and the hollow arrow pointing to the source. The difference you see on your screen 
is that parameter connections are violet instead of cyan. 

In addition, the parameter names are included in the connection menu. Therefore, if 
you are in doubt about a connection that you want to make, you can browse a part’s 
features to see the parameter names. Be aware, however, that any parameter names 
that you specified for an action in the Parameter Names table on the Action page of 
the Part Interface Editor appear in the connection menu instead of the actual 
parameter names. 

The parameter is always the source of the connection because the parameter cannot 
store any values. If you connect an attribute, action, member function, or custom 
logic to a parameter, which makes the parameter the target of the connection. Visual 
Builder reverses the direction to make the parameter the source. 

Whenever the parameter needs a value, the connection attempts to satisfy the 
parameter in one of the following ways: 

• If the parameter is connected to an attribute, the connection invokes the 
attribute’s get member function to get the attribute’s value and return it to the 
parameter. 

• If the parameter is connected to an action, the connection invokes the action and 
passes the action’s return value to the parameter. The same is true when a 
parameter is connected to a member function or to custom logic. 

• You can supply a constant parameter value. See “Satisfying Parameters for 
Incomplete Connections” on page 179 for information about doing this. 

If you connect a parameter to two different attributes, the first attribute that you 
connect the parameter to has precedence over the second. You can change this, if 
necessary, by reordering the connections or deleting one of the connections. 
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Visual Builder uses a dashed line to give you a visual cue so that you know when a 
parameter connection is needed. For example, if you connect an event to a member 
function and the member function has a parameter that needs to be satisfied, the 
connection line between the event and the member function is dashed. See 
“Satisfying Parameters for Incomplete Connections” on page 179 for more 
information about parameter connections. 


Connection Type Summary 

The following table summarizes the types of connections that Visual Builder 
provides: 


If you want to... 

Use this 

connection 

type 

Color 

Arrows 

Return value 

allowed? 

Cause one data 
value to change 
another 

attribute-to- 

attribute 

Cyan 


No 

Change a data 
value whenever 

an event occurs 

event-to- 

attribute 

Dark green 

- -► 

Yes 1 

Invoke an action 

whenever an 

event occurs 

event-to- 

action 

Dark green 

- -► 

Yes 1 

Invoke a 

member function 

whenever an 

event occurs 

event-to- 

member 

function 

Light green 

- ► 

Yes 1 

Invoke an action 

whenever a data 
value changes 

attribute-to- 

action 

Dark green 

- > 

Yes 1 

Invoke a 

member function 

whenever a data 
value changes 

attribute-to- 

member 

function 

Light green 

- ► 

Yes 1 

Call customized 

custom logic 

Blue 

- ► 

Yes 1 


code whenever a 
data value 
changes or an 
event occurs 


1 The return value is supplied by the connection’s actionResult attribute. 
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If you want to... 

Use this 

connection 

type 

Color 

Arrows Return value 

allowed? 

Satisfy a 

parameter 

Violet 

Yes' 

parameter with a 




data value 





Making the Connections 

In this section, you leant how to make attribute-to-attribute, event-to-attribute, 
event-to-action, and attribute-to-action connections. 

The other connection types, event-to-member function and attribute-to-member 
function connections, are discussed in “Connecting Features to Member Function 
Connections” on page 183. 

Determining the Source and Target 

A connection is directional; it has a source and a target. The direction in which you 
draw the connection determines the source and target. The part on which the 
connection begins is the source and the part on which it ends is the target. 

When you make a connection. Visual Builder draws an arrow on the connection line 
between the two parts. The arrow points from the source to the target. If 
information can pass through the connection in both directions, as it can in an 
attribute-to-attribute connection, a hollow arrow points to the source and a solid arrow 
points to the target. 

Often, it does not matter which part you choose as the source or target, but there are 
connections where direction is important. Here are the source and target rules: 

• With an attribute-to-action, event-to-action, or event-to-attribute connection, the 
event is always the source and the action or attribute is always the target. If you 
try to make an action-to-attribute, action-to-event, or attribute-to-event 
connection, Visual Builder automatically reverses it for you. 

• For attribute-to-attribute connections, if only one of the attributes has a set 
member function Visual Builder makes that attribute the target. This is done so 
that the attribute that has the set member function can be initialized when the 
application starts. 

• When you make attribute-to-attribute connections, the order in which you choose 
the source and target is important. The source and target attribute values are 
probably different when your view is first initialized. If they are. Visual Builder 
resolves the difference by changing the target end of the connection to match the 
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source. Thereafter, if both attributes have set member functions, the connection 
updates either attribute if the other changes. 

Refer to the attributes, actions, and events sections of the particular part in the Visual 
Builder Parts Reference for information that is specific to a part’s features. 

Browsing a Part’s Features 

Sometime it is useful to browse a part’s features before using them in a connection. 
For example, you might want to look at an attribute to see if it has a set member 
function so that it can update itself when it receives new data from another attribute. 

By using Browse Part Features, you can see all of a part’s features in one window 
and browse, but not change, the information about each feature. To modify a feature, 
use the Part Interface Editor. 

There is an important distinction between browsing a part’s features and displaying its 
features for making a connection. When you browse a part’s features, you see all of 
its features, including inherited and promoted features, even if some of them are not 
available for connections. When you display a part’s connection menu, however, you 
see only those features that are available for connections. 

To browse the features of a part, do the following: 

1. Move the mouse pointer over the part and click mouse button 2. 

Visual Builder displays the part’s pop-up menu. 

2. Select Browse Part Features. 

Visual Builder displays a browse window that contains three columns: one for 
actions, one for attributes, and one for events. For example, the following figure 
shows the browse window that Visual Builder displays for browsing the features 
of a push button: 
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gg| IPushButton - Feature Implementation Browser 


□ 


Action 

applyBidiSettings 

capturePointer 

click 

convertToGUIStyle 

disable 

disableDefault 
disableGroup 
disableHelp 
disableMouseClickFt, 


Attribute 

activeColor 

allowsMouseClickF 

asDebuglnfo 

asString 

autoDeleteObject 

autoDestroyWindo 

backgroundColor 

bidiSupported 

border 


Event 

buttonClickEvent 

commandEvent 

gotFocusEvent 

inputDisabledEvent 

inputEnabledEvent 

lostFocusEvent 

systemCommandEvt 

visibilityDisabledEve 

visibilityEnabledEve 


Attribute type 
Get function 
Set function 
Event Id 


Description 
Close Refresh 


Help 


Figure 71. Browse Part Features Window 

3. Select the feature you want to browse. 

Visual Builder displays information about the feature that you select in the entry 
fields below the feature columns. Different sets of entry fields are displayed 
depending on whether you select an attribute, an event, or an action. 

The information that Visual Builder displays when you browse a part’s features is 
the same as the information that you would see in the Part Interface Editor. See 
“The Part Interface Editor” on page 57 to learn about the information that Visual 
Builder displays for features. 

4. If the information about a part’s features should change, you can select the 
Refresh push button to see those changes reflected in the browse window. 

5. When you have finished browsing the features, select the Close push button to 
close the browse window. 
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Connecting Features to Features 

When you connect features to features, you can use any of the following source-target 
combinations: 

If source is a... The target can be a... 

part part or connection 

connection part 

Follow these steps to connect features: 

1. Position the mouse pointer over the source, the part or connection that you want 
to connect from, click mouse button 2, and select Connect from its pop-up 
menu. 

e 

A menu appears showing the names of the most commonly used attributes, 
actions, and events, called the preferred features. If the source is a part, there is 
usually a More selection at the bottom of the list. 

If the More selection is not there, this means the list contains all of the available 
features, not just the preferred ones, and there are no more from which to select. 

2. Do one of the following: 

• If the feature you want appears in the list, select it. 

• If the feature you want does not appear in the list, but the More selection is 
available, select More and then select the feature you want from the 
complete list of features. 

• If the feature you want does not appear in either the preferred list or the 
expanded list that is displayed when you select More, you can edit the part 
to add the feature you need. For more information about this, see “Editing 
Parts Placed on the Free-form Surface” on page 153. 

e 


If, at this point, you decide not to complete the connection, do one of the 
following: 

• If a pop-up menu is displayed, move the mouse pointer away from the 
connection menu and click mouse button 1. 

• If a window showing all of the features is displayed, select the Cancel 
push button at the bottom of the window. 

The menu or window disappears and the connection is not completed. 


To display the connection pop-up menu more quickly, hold down the Alt 
key while clicking mouse button 2. 
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3. Position the mouse pointer over the part or connection that you want to connect 
to. 

While moving the mouse, notice that a dashed line trails from the mouse pointer 
to the source of the connection. 

4. Click mouse button 1 and a pop-up menu appears, again showing a list of 
features. 

5. Select a name from the pop-up menu or from the More list. 

The same instructions regarding the presence of More apply as described 
previously. 

A colored connection line appears when both ends of the connection have been made. 
The color indicates the connection’s type, based on the selections you made in the 
connection pop-up menu. See “Connection Type Summary” on page 174 for a table 
that shows the colors that are used for each connection type. 

If the line is dashed, it requires parameters, as described in the next section. 

Satisfying Parameters for Incomplete Connections 

Event-to-action, attribute-to-action, event-to-attribute, event-to-member function, and 
attribute-to-member function connections sometimes require parameters, or input 
arguments. If a connection requires parameters that have not been specified, it 
appears as a dashed arrow indicating that it is incomplete. When you have made all 
the necessary parameter connections, the connection line becomes solid indicating that 
the connection is complete. 

The following sections describe how to complete connections when input parameters 
are required and how to change source and target features without deleting a 
connection and starting over. 

Satisfying a parameter using a connection 

One way to satisfy parameters is to make connections from the dashed connection 
lines to the parts that supply the values to the parameters. Most of the time, the 
values you need are those of attributes of other parts that you are working with in the 
Composition Editor. Sometimes, however, the value you need is the return value 
from an action, a member function, or custom logic. 

To supply a parameter value, do the following: 

1. Start a new connection using the dashed connection line that requires the 
parameter as the source. 
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2. For the target, select the attribute, action, member function, or custom logic that 
is to provide the value that the parameter needs. 

While making a connection, when the mouse pointer is directly over the 
connection line, you see a small box as a visual cue that the pointer is 
positioned correctly. 


The following example illustrates how to complete a connection using an attribute to 
supply the input value to the parameter. The figure shows an incomplete 
event-to-action connection. When a user selects the Add push button, its 
buttonClickEvent feature notifies the addAsLast action of the IListBox* part to add 
something to the list box as the last item in the list. The connection is incomplete 
because the addAsLast action has a parameter that needs an input value, which is the 
text to add to the list box. 



Add 


Remove 


Figure 72. Incomplete Connection Due to Missing Parameter Value 


The next example shows how a parameter connection, in which an attribute of the 
IEntryField* part is used to supply the input value for the parameter, completes the 
event-to-action connection shown in Figure 72. The text parameter of the incomplete 
connection is connected to the text attribute of the IEntryField* part. Therefore, when 
the Add push button is selected, its buttonClickEvent feature notifies the addAsLast 
action of the IListBox* part to add the text in the IEntryField* part as the last item in 
the list box. 
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Figure 73. Completing a Connection Using an Attribute as the Input Value 


The return type of an action displays as the actionResult attribute of the 
connection. For example, you can connect the actionResult attribute to an 
attribute of the same part or another part. 


Satisfying a parameter using a constant value 

When connections need parameters whose input values are constant, you provide 
these values by using the settings window of the incomplete connection, as follows: 

1. Select Open settings from the incomplete (dashed) connection’s pop-up menu. 

A quicker way to open the settings window is to double-click on the 
connection line. 

The settings window of the incomplete connection is displayed. 

2. Select the Set parameters push button. 

The Constant Parameter Value Settings notebook is displayed showing the 
parameters for which you can set constant values. 

3. Enter the constant parameter values you want to use. 

Type the parameter values just as you would type them as parameters for the 
member function if you were coding it by hand. For example, to provide a 
constant value for a text parameter, enter the text string that you want the 
parameter to receive. Visual Builder copies them as strings to the output files 
when you generate your default code. 
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In event-to-attribute connections, the attribute’s set member function 
sometimes has more than one parameter. In this case. Visual Builder only 
allows you to provide a constant parameter value for the first parameter. 

The other parameters are given default settings. 

For example, a set member function called setRange might have a range 
parameter and an override parameter. If you followed the instructions 
provided in this section, when you selected the Set parameters push button 
the settings page would only provide a field for a constant value for the 
range parameter; you would not be given an opportunity to change the 
default setting of the override parameter. 

To change the default values assigned to parameters, use a custom logic 
connection. See “Connecting Features to Custom Logic” on page 188 for 
information about making custom logic connections. 


4. Do one of the following: 

• Select the OK push button to apply the values and save them. 

• Select the Apply push button if you want to see what effect these values 
have before saving them. 

• Select the Cancel push button to remove the notebook without saving any of 
the parameter values you entered. 

You can select Help for additional information about entering parameter values. 

Specifying defaults for parameters 

There are two places in Visual Builder in which you can specify defaults for the 
parameters of actions in the declaration of the action’s member function: 

• In the part’s .vbe file 

• On the Action page of the Part Interface Editor 

Either of these allows a default value to be passed in an event-to-action connection, 
thus avoiding the need to satisfy a parameter. 

For example, suppose you want to connect the buttonClickEvent feature of a Remove 
push button to a removeSelected action that you created for an IListBox* part. 
Normally, you would also need to connect the selection attribute of the subclassed 
IListBox* part to the index attribute of the connection between buttonClickEvent and 
removeSelected. This connection would be required to get the index of the selected 
item in the list box. 

However, in the .vbe file of the IListBox* part, you can specify the following default 
parameter value for the removeSelected action: 
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//VBAction: removeSelected, "removeSelected",, 

//VB: removeSelected(unsigned long index=selection()) 

This means that if no attribute of the IListBox* part is connected to the index 
attribute, the selection member function (the get member function of the selection 
attribute) is called by default to provide the index of the selected item. 

You could do the same thing by creating a removeSelected action on the Action page 
of the Part Interface Editor for the IListBox* part. You would specify the default 
parameter in the declaration of the removeSelected member function in the Action 
member function field, as follows: 

virtual unsigned long removeSelected(unsigned long index=selection()) 

Missing or invalid parameters 

When an action connection requires arguments, be sure that you make the correct 
number of parameter connections. Also be sure that you make the parameter 
connections before you generate the default code for your part. See “Manipulating 
Connections” on page 194 to leant how to re-order connections. 


Connecting Features to Member Function Connections 

A common use for member functions is with event-to-member function connections 
and attribute-to-member function connections. These connections link an event to a 
member function so that the member function is called when the event occurs. 
Event-to-member function connections make this link directly from an event to a 
member function connection. Attribute-to-member function connections make this 
link indirectly using the attribute’s event identifier, passing the value of the attribute 
as the first parameter of the member function. The member function that you connect 
the event or attribute to must belong to the part being edited. 

For example, suppose you are creating a composite part that consists of several 
individual parts, such as a frame window, an entry field, a list box, and two push 
buttons. In this case, you can connect the attributes and events of all individual parts 
to a member function that belongs to the composite part that you are editing. 

When to connect attributes or events to member functions 


How do you know when to connect an attribute or event to an action and when to 
connect it to a member function? After all, an action is simply a member function 
with a part interface. Therefore, it seems there should be little difference between 
connecting to one and connecting to the other. 
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The difference is accessibility. Anyone can use actions that you include in your 
part’s interface, but only you can use the member functions that belong to your part. 
When you create actions and include them in your part’s interface, other programmers 
who use your part can create their own event-to-action or attribute-to-action 
connections using the actions that you have defined for the part. That is the reason 
for including functions in the part’s interface as actions—to make them available to 
other programmers. 

However, you may have functions that you want to invoke for your part without 
including them in the part’s interface. For example, your part may need to perform a 
calculation internally whenever the value of an attribute changes. However, another 
programmer who is using your part may not need to be aware that this is happening. 
This is when you use member functions instead of actions. By using 
event-to-member function connections and attribute-to-member function connections, 
you can call these member functions when specific events occur or when attribute 
values change, but no one else can. 

Adding an Event-to-Member Function Connection 

The requirements for connecting an event to a member function are a visual part that 
has at least one event specified for it, as well as at least one member function. 

The following figure shows the OAContractorView part used in the OASearch sample 
application in this book. The steps for adding an event-to-member function 
connection, which follow the figure, are based on this part. For information about 
how to construct this part, see “Adding Notebook Parts” on page 240. 
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[E7 OAContractorView - Composition Editor 


Opportunities Abound Contractor Information 


File Edit View Options Tools Help 


Home Address 


Postal Code 


Phone 


MessageBoxI 
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SkillBase 


□ Sticky 


Notebookl selected. 


Figure 74. OAContractorView Notebook 

1. With the mouse pointer over the Clear push button, hold down the Alt key and 
click mouse button 2. 

Visual Builder displays the connection menu for the Clear push button. 

2. From this menu, select the buttonClickEvent choice, an event. 

3. Move the mouse pointer to a point on the free-form surface outside the 
OAContractorView notebook part and click mouse button 1. Doing this 
indicates to Visual Builder that you want to connect the event to the 
OAContractorView notebook part instead of one of its subparts. 

Visual Builder displays the connection menu with the preferred features that have 
been defined for OAContractorView. The member function that you want to 
connect your event to is not on this menu. Member functions are not considered 
to be preferred features unless you define them as actions in the Part Interface 
Editor. 

4. Select More. 
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Visual Builder displays a window that contains three list boxes. The left and 
middle boxes show the actions and attributes of the OAContractorView notebook 
that you can connect the buttonClickEvent feature to. The third list box is for 
events; this list box is empty because you cannot connect one event, in this case 
buttonClickEvent, to another event. 

Below the three list boxes is another section of the window titled Member 
Function Connection. This is where you specify the member function that you 
want to connect the buttonClickEvent feature to. 

The For class field contains the class name of the part that you are editing. This 
field is actually a drop-down list box. The list box is initially empty. See the 
definition of the Browser pull-down menu item in “Using Browser Information” 
on page 187 to find out how to display the names of the classes that your part 
inherits from, as well as how to display the member functions that your part 
contains in the list box at the bottom of the window. 

For this example, the For class field should contain OAContractorView, the part 
that you are editing. 

The Access field is another drop-down list box. This field is where you specify 
the access level (public, protected, or private) for the member functions that you 
want to see in the list. You must open the Browser data to see a list of member 
functions. See “Using Browser Information” on page 187 to learn how to do 
this. 

For this example, the Access field should contain public. 

5. Type the member function to which the buttonClickEvent feature is to be 
connected in the entry field below the Access field. Be sure to type the full 
declaration of the member function, including return type and parameters. 

For this example, enter the following member function to clear all of the fields in 
OAContractorView: 

void resetFields(); 

You must also create an .hpv file that contains this member function declaration 
and a .cpv file that contains the code for this member function. The member 
function declaration that you enter in this field must be identical to the 
declaration that you put in the .hpv file. For information about .hpv and .cpv 
files, see “Specifying Files to Include When You Build Your Application” on 
page 56. 

In addition, before you generate the code for your part, you must switch to the 
Class Editor and enter the names of these files so that Visual Builder will include 
them in the code for your part. For more information about including these files, 
see “Specifying Files to Include When You Build Your Application” on page 56. 

6. Select the OK push button. 
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The connection window disappears and a light green connection arrow is drawn 
from the Clear push button toward the edge of the free-form surface. It looks 
like this: 


Refresh 


Save Cl ear | Cancel | 

Vital statistics ♦II+1 


Figure 75. Completed Event-to-Member Function Connection 

If the resetFields member function had parameters, the connection arrow would 
be dashed instead of solid to give you a visual cue that you would need to 
provide values for the parameters. For information about the various ways to do 
this, see “Satisfying Parameters for Incomplete Connections” on page 179. 

Using Browser Information 

When connecting attributes or events to member functions, you might find it helpful 
to see the classes and member functions in your inheritance tree, as well as member 
functions that your part contains. You can get this information by selecting 
File—^Browser when using any of the Visual Builder editors. This menu choice 
provides access to a list of the classes that your part inherits from. 

You can use this list when you make attribute-to-member function and 
event-to-member function connections. The window that Visual Builder displays 
when you are making these connections contains a drop-down list box titled For 
class. In this list box, you can select one of the classes that your part inherits from. 
This causes Visual Builder to display a list of the member functions that the class 
contains in another list box at the bottom of the connection window. 

The connection window is modal. Therefore, to display browser data in this window, 
you must select the Open browser data menu choice described on page 188 before 
you begin the connection. Otherwise, the For class drop-down list box contains only 
the class name of your part, and the member function list box can display only the 
member functions that your part contains. 

The VisualAge C++ compiler generates the browser information when you have 
compiled your application. Therefore, except for the Quick browse menu choice, 
browser information is not available until after you compile your application. 
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The VisualAge C++ compiler stores the browser information in a file whose name is 
based on the part name and whose extension is .pdb. To generate this file, you must 
include the -Fb+ compiler option in your make file. 

The cascaded menu that Visual Builder displays when you select File—^Browser 
contains the following selections: 

Quick browse 

Causes Visual Builder to retrieve a list of the classes that the part you are editing 
inherits from, as well as a list of the member functions that your part and the part 
it inherits from contains. If you select one of the classes in the list. Visual Builder 
retrieves a list of the member functions that the class contains. 

This function is available only if you start Visual Builder from a WorkFrame 
project. It gives you access to browser information before you compile your 
application. 

Open browser data 

Works the same as Quick browse except you must compile your application with 
the -Fb+ option before using this function. Also, you do not have to start Visual 
Builder from a WorkFrame project to use this function. 

Refresh browser data 

Refreshes the list of the classes that the part you are editing inherits from, as well 
as the list that is displayed in the member function list box for the current class. If 
you reparse a part or recompile your application, use this function afterwards to 
ensure the data in the list boxes is current. 

Close browser data 

Removes the list of the classes that the part you are editing inherits from, as well 
as the member functions those classes contain. 


Connecting Features to Custom Logic 

Custom logic connections enable you to connect small, specialized code snippets to 
events and attributes. These connections link an event to your code so that it is 
called when the event occurs. Custom logic connections that use events make this 
link directly from an event to the custom logic; custom logic connections that use 
attributes make this link indirectly using the attribute’s event identifier. 

Use custom logic for unique logic requirements because the logic is stored as part of 
the connection and is not reusable. 
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Adding a Custom Logic Connection 

The requirements for connecting an event or attribute to custom logic are a visual part 
that has at least one event or attribute specified for it. Following are the steps to 
follow for adding a custom logic connection. The following figure shows the History 
page of the OAContractorView part used in the OASearch sample application in this 
book. The example used in the following steps is based on this part. 



Figure 76. OAContractorView Part 

1. Select the right arrow in the lower right corner of the notebook to display the 
History page. 

2. With the mouse pointer over the Clear push button, hold down the Alt key and 
click mouse button 2. 

Visual Builder displays the connection menu for the Clear push button. 

3. From this menu, select the buttonClickEvent choice, an event. 

4. Move the mouse pointer to a point on the free-form surface outside the 
OAContractorView part and click mouse button 1. Doing this indicates to 
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Visual Builder that you want to connect the event to the OAContractorView part 
instead of one of its subparts. 

Visual Builder displays the connection menu with the preferred features that have 
been defined for the OAContractorView part. 

5. Select Custom logic. 

Visual Builder displays the following window: 


Custom logic connection - New 


ClearPB2 —> OAContractorView 


Cl. 


□ 


Description: 

Event name: buttonClickEvent 
Return type: void 
Custom logic 


mmm 


Add Cancel Source Target Help 


Figure 77. Window for Connecting Event to Custom Logic 

6. Enter the following in the Description field: 

Custom logic code to clear all entry fields 

The Description field serves two purposes. After you complete the connection, 
if you select the connection line Visual Builder displays the text that you entered 
in this field in the information area at the bottom of the Composition Editor. 
Also, when you generate the code for this part. Visual Builder inserts a comment 
line that contains this description. 

7. The buttonClickEvent feature is the event you want to connect to your custom 
logic, so do not change the Event name field for this example. 

This field contains the event that you selected previously from the connection 
menu. You can change this by selecting an event name from the drop-down list 
box. 

8. The default return type of void is the return type you want to use, so do not 
change the Return type field for this example. 

This field contains the return type for your custom logic. If you leave void as 
the return type, your custom logic will have no return value. If you want to pass 
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a return value from your custom logic to another part, a member function, or 
other custom logic, be sure to change the return type to the type of data that you 
want to pass. 

9. Select the Target push button. 

Visual Builder inserts target-> in the Custom logic field. 

The Custom logic field is a multiline entry field. This is where you enter your 
custom logic. You can specify whether the code you enter here is to effect the 
source part or the target part by selecting the Source or Target push button 
before entering a line of code. You only need to select one of these push buttons 
before entering the first line of a group of lines. 

In the generated code, the entry fields that we want to clear are created using the 
new operator. For the StartEF part, the resulting pointer is called iStartEF. 

10. Type the following to the right of target->: 
i StartEF->removeAl1(); 

This code calls the removeAll member function for the StartEF part, the entry 
field labeled OA Start Date. 

11. Press the Enter key to move the cursor to a new line. 

12. Select the Target push button again. 

13. Type the following to the right of target->: 
iEndEF->removeAl1 (); 

This code calls the removeAll member function for the EndEF part, the entry 
field labeled OA End Date. 

14. Press the Enter key to move the cursor to a new line. 

15. Select the Target push button again. 

16. Type the following to the right of target->: 
i ContractEF->removeAl1(); 

and put the following line beneath it: 
return; 

This code calls the removeAll member function for the ContractEF part, the entry 
field labeled Current Contract. 
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The connection window should now look like the following figure: 


Custom logic connection - Settings 


ClearPB2 —> OAContractorView 


Description: 

Sample to clear entry fields 


Event name: 

buttonClickEvent 

i- 

Return type: 

void 



Custom logic 

target->iStartEF->removeAII(); 

target->iEndEF->removeAll(); 

target->iContractEF->removeAU(); 

return; 

± 

Update Cancel Source Target Help 


Figure 78. Completed Custom Logic Connection Window 


17. Select the Add push button. 

The connection window disappears and a blue connection arrow is drawn from 
the Clear push button toward the edge of the free-form surface. It should look 
like this: 










Figure 79. Completed Custom Logic Connection 


Connecting Exception Events to Actions and Member Functions 

In C++, an exception is any user, logic, or system error detected by a function that 
does not deal with the error itself but passes the error on to a handling routine, called 
an exception handler. In Visual Builder, you can catch exceptions by connecting an 
exception event to either an action or a member function. 

An exception event is a feature of a connection, not a part. It is typically connected 
to an IMessageBox* part, which is used to display an error message associated with 
the exception. 

To connect an exception event, do the following: 
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1. Use your favorite text editor to create an action or member function that throws 
an exception. 

The easiest way to do this is to include the following in your action or member 
function source code: 

throw IException("Error message."); 

where the text of the error message that you want to display in the message box 
is the only parameter given for the Exception constructor. 

For example, the following isEntryFieldEmpty member function uses the strcmp 
function to check the contents of an entry field in a To-Do List application. The 
application adds the contents of the entry field to the to-do list whenever the user 
clicks the Add push button. If the entry field is empty and the user clicks on 
Add, the member function throws an exception, which consists of an error 
message. 

void ToDoList: :isEntryFieldEmpty() 


if 


1 


(strcmp(this->iEntryField->text(), "") == 0) 

throw IException("Type a to-do item in the entry field 
before selecting Add."); 


2. Connect an event to the action or member function you just created. 

The event that you connect here is the event for which you want to throw an 
exception if an error occurs. In this example, you want to throw an exception if 
the user clicks on Add when the entry field is empty. Therefore, you would 
connect the buttonClickEvent feature on the Add push button to the 
isEntryFieldEmpty member function. 

3. Drop an IMessageBox* part on the free-form surface. 

This message box is used to display the error message. 

4. Move the mouse pointer to the connection you just made. 

5. While holding down the Alt key, press mouse button 2. 

6. Select the exceptionOccurred event from the connection menu. 

7. Move the mouse pointer to the IMessageBox* part. 

8. Click mouse button 1. 

9. Select the show action from the connection menu. 

This connection causes the application to show a message box that contains the 
exception error message whenever the exception is thrown. 


For an example using the OAContractorView part from the OASearch application, see 
“Passing Exceptions to Message Boxes” on page 209. 
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Manipulating Connections 

Once a connection is made, you can manipulate it by doing the following: 

• Changing settings for a connection 

• Reordering connections 

• Deleting connections 

• Showing and hiding connections 

Changing Settings for a Connection 

The settings window of a connection provides a way for you to select different 
features as the source and target of the connection. If a member function is the target 
of the connection, this window allows you to specify or select a different member 
function as the target. 

Note: If you are changing the settings of a connection whose target is a member 

function, you might want the connection settings window to show the classes 
that your part inherits from, as well as the member functions that those classes 
contain. To display the class and member function names, you must open the 
browser data before opening this settings window. See “Using Browser 
Information” on page 187 for information about opening browser data. 

To open the settings window for a connection, move the mouse pointer over the 
connection and do one of the following: 

• Double-click mouse button 1. 

• Click mouse button 2 and select Open settings from the connection’s pop-up 
menu. 

Visual Builder displays different connection settings windows depending on whether 
the target of the connection is an attribute, action, or member function. The 
following sections describe these three windows. 

Changing Settings for Attribute-to-Attribute Connections 

The following figure shows the window that Visual Builder displays when you open 
the settings window for an attribute-to-attribute connection: 
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H Attribute-to-attribute connection - Settings 


'Contractor' (ttcurrentContract) —> 'ContractEF' (tttext) 


Contractor ContractEF 



H size H 

enabledForNotification 

tabStop 

endDate 


firstName 

valueAsDouble 

homeCity 

valueAsInt 

homeState 

valueAsUnsigned 

homeStreet 

visible 

homeZip 

v writeable H 


[°L 

Reverse 

Delete Cancel 

Help 


Figure 80. Attribute-to-Attribute Connection Settings Window 

The connection settings window for an attribute-to-attribute connection contains two 
columns of attributes. The left column contains the attributes that belong to the 
source part. The right column contains the attributes that belong to the target part. 

To change the attribute to be used as either the source or target of the connection, 
select an attribute from the list. 

This connection settings window has the following push buttons: 

OK 

Removes the connection settings window and puts any changes made into effect. 

Reverse 

Reverses the order of the connection; the source part becomes the target and the 
target part becomes the source. 

Delete 

Deletes the connection. 

Cancel 

Removes the connection settings window without putting any changes into effect. 

Help 

Provides helpful information about the window. 
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Changing Settings When an Action Is the Target 

When you open a settings window for a connection whose target is an action. Visual 
Builder displays the following window: 


|[H Event-to-action connection - 

Settings 

□ 

'RefreshPB2' (tfbuttonClickEvent) 

—> 'Contractor' (BgetContractor) 

RefreshPB2 

Contractor 

Event 

Action 

1 buttonClickEvent 



commandEvent 

homeCIty 


disabledBackgroundColor 

homeState 


disabledForegroundColor 

homeStreet 


enabled 

homeZip 


focus 

lastName 


font 

middlelnitial 


foregroundColor 

notifyObservers 


gotFocusEvent 

operator = 


hiliteBackgroundColor 

parseName 


hiliteForegroundColor 

^ phoneNumber 

V 

□ _l LJ _J 


| OK | Cancel DeleteJ j Se 

1: parameters... Help 


Figure 81. Connection Settings Window with an Action as the Target 

The connection settings window contains two columns of features. The features in 
the left column belong to the source part; these features are the same type of feature 
as the one currently selected for the source part. For example, if the feature selected 
for the source part is an event, this column contains a list of the events that belong to 
the source part. 

Likewise, the features in the right column belong to the target part; these features are 
all actions or attributes that have set member functions. 

The entry fields above each list contain the names of the features that are currently 
selected. To change the feature to be used as either the source or target of a 
connection, select a feature from the list. 

This connection settings window has the following push buttons: 

OK 

Removes the connection settings window and puts any changes made into effect. 

Cancel 

Removes the connection settings window without putting any changes into effect. 

Delete 

Deletes the connection. 
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Set parameters 

Opens another window in which you can specify a constant parameter value for 
each parameter the action has. 

Help 

Provides helpful information about the window. 

Changing Settings When a Member Function Is the Target 

Two types of connections can use a member function as the target: 
attribute-to-member function and event-to-member function connections. The 
following figure shows a settings window for an event-to-member function 
connection: 


jail Event-to-member-function connection - Settings 


ClearPBI Event name: buttonClickEvent 


Select or enter the member function signature: 

For class OAContractorView 

V 1 

r ; 

Access public - 


resetFieldsO 


| resetFieldsO 

S 


Cancel | | Delete | | Set parameters... 


Help 


Figure 82. Connection Settings Window with a Member Function as the Target 


The Event name or Attribute name field 


The Event name field shows the name of the event that is connected to the member 
function. If this was an attribute-to-member function connection, this field would be 
the Attribute name field and would contain an attribute name. 

To change this name, select an attribute or event from the drop-down list box below 
the entry field. 
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The For class field 


The For class field shows the name of the class that the target member function 
belongs to. This field can contain either the class name of the part that you are 
editing or the class name of a part that the part you are editing inherits from. 

To change this class name, select a class name from the drop-down list box below the 
entry field if you opened the browser data before opening this window. 

The Access field and member function list 


The Access field shows the current access type, which is either public, protected, or 
private. Member functions of this access type that belong to the class shown in the 
For class field are displayed in the list box at the bottom of the window. These 
member function names are displayed only if you opened the browser data before 
opening this window. The list includes the currently selected member function, 
which is shown in the entry field above the list. 

To change the access type, do one of the following: 

• Move the mouse pointer over the Access field, click mouse button 1, and type 
the letter p. 

Each time you type the letter p, the next access type appears. For example, if 
the entry field contains public, typing the letter p causes protected to appear. 

• Select an access type from the drop-down list box. 

To change the member function that is used for the connection, do one of the 
following: 

• Type a different member function in the entry field. 

• Select a member function from the list displayed below the entry field if you 
opened the browser data before opening this window. 

The push buttons 

The connection settings window for member functions has the following push 
buttons: 

OK 

Removes the connection settings window and puts any changes made into effect. 

Cancel 

Removes the connection settings window without putting any changes into effect. 
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Delete 

Deletes the connection. 

Set parameters 

Opens another window in which you can specify a constant parameter value for 
each parameter the member function has. 

Help 

Provides helpful information about the window. 

Changing Settings When Custom Logic Is the Target 

The following figure shows a settings window for a custom logic connection: 


Custom logic connection - Settings 


ClearPB2 —> OAContractorView 


Description: 

Sample to clear entry fields 


Event name: 

buttonClickEvent 

= 

Return type: 

void 



Custom logic 

farget->iStartEF->removeAII(); 

target->iEndEF->removeAU(); 

target->iContractEF->removeAll(); 

return; 

> 

Update Cancel | Source | | Target | I Help 


Figure 83. Connection Settings Window with Custom Logic as the Target 

The fields in this window are the same as those used to create the connection. See 
“Adding a Custom Logic Connection” on page 189 for information about these fields 
and push buttons. 

The only push button that differs on this window is the Update push button. Use this 
push button to save any changes you make and close the window. 

Reordering Connections 

If you make several connections from the same part, they run in the order in which 
you made the connections. To ensure the correct flow of control when you generate 
the source code, you may need to reorder the connections. If so, do the following: 

1. Select the source part. 

2. From the source part’s pop-up menu, select Reorder Connections From. 
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Visual Builder displays the Reorder Connections window showing a list of your 
connections. 

3. With the mouse pointer over the connection you want to reorder, press and hold 
mouse button 2. 

4. Drag the connection to the place in the list where you want the connection to 
occur. 

5. Release mouse button 2. 

6. Repeat these steps until the connections are listed in the order in which you want 
them to occur. 

7. Close the window. 


Deleting Connections 

You can delete a connection in either of the following ways: 

• From the connection’s pop-up menu. 

Note: You do not have to select a connection to delete it using this method. 

To delete a connection from its pop-up menu, do the following: 

1. Click on the connection with mouse button 2 to display its pop-up menu. 

2. Select Delete. 

• From the connection’s settings window 

To delete a connection from its settings window, do the following: 

1. Open the settings window for the connection by doing one of the following: 

- Double-clicking on the connection 

- Clicking on the connection with mouse button 2 to display its pop-up 
menu and selecting Open Settings 

2. Select the Delete push button. 

Showing and Hiding Connections 


You can show and hide connections by using 


P'-T 


_nJ 


, the Hide Connections tool. 


and 


run 


_nJ 


, the Show Connections tool on the Tool bar. These tools show or hide 


all connections that have the selected part or parts as their source or target. If no 
parts are selected, these tools show or hide all of the connections. 
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If you hide connections, the Composition Editor free-form surface is drawn 
faster and is less cluttered, making it easier for you to work. 

If no parts are selected, these tools show and hide all of the connections in the view. 
If a part or parts are selected, these tools show and hide the connections between the 
selected part or parts. 

Another way to show and hide connections is to move the mouse pointer over a part, 
click mouse button 2, and select the Browse Connections choice from the part’s 
pop-up menu, which displays a cascaded menu. The choices in the menu affect only 
connections going to and from the part the mouse pointer was over when you 
displayed the pop-up menu. 

The Browse Connections cascaded menu contains the following choices: 

Show To 

Shows all connections for which the part is the target. 

Show From 

Shows all connections for which the part is the source. 

Show To/From 

Shows all connections for which the part is either the source or the target. 

Show All 

Shows all connections that have been made, regardless of where the mouse pointer 
is when you click mouse button 2. 

Hide To 

Hides all connections for which the part is the target. 

Hide From 

Hides all connections for which the part is the source. 

Hide To/From 

Hides all connections for which the part is either the source or the target. 

Hide All 

Hides all connections that have been made, regardless of where the mouse pointer 
is when you click mouse button 2. 
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Rearranging Connections 

You can rearrange a connection by doing the following: 

• Selecting connections 

• Deselecting connections 

• Changing the source and target of connections 

Selecting Connections 

You select connections in the same way that you select parts. When you select a 
connection, three boxes called selection handles appear on it to show that it is 
selected: one at each end and one in the middle. You can use these boxes to change 
either of the following: 

• The end points of the connection, as described in “Changing the Source and 
Target of Connections” on page 203. 

• The shape of the connection arrow by dragging the middle box to another 
location. This helps you distinguish among several connection lines that are 
close together. 

Selecting a single connection 

1. Move the mouse pointer over the connection you want to select. 

2. Click mouse button 1 to select the connection. 

The connection is selected. 

Selecting multiple connections 

If you want to select several connections, do one of the following: 

• To select multiple connections using just the mouse, do the following: 

1. Move the mouse pointer over one of the connections you want to select. 

2. Hold down mouse button 1 instead of clicking it. 

3. Move the mouse pointer over each connection that you want to select. 

The selection boxes appear on each connection that the mouse pointer passes 
over to show they are selected. 

4. After the connections are selected, release mouse button 1. 

• To select multiple connections using both the mouse and the keyboard, do the 
following: 

1. Hold down the Ctrl key. 

2. Move the mouse pointer over a connection. 
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3. Click mouse button 1 while the mouse pointer is over the connection line. 

4. Without releasing the Ctrl key, repeat the preceding steps until all 
connections that you want to select are selected. 

Deselecting Connections 

If you want to deselect a connection without selecting another part or connection, do 
the following: 

1. Move the mouse pointer over the connection line. 

2. Hold down the Ctrl key. 

3. Click mouse button 1. 

Changing the Source and Target of Connections 

Visual Builder gives you the ability to change what a connection is pointing to (the 
target) or pointing from (the source). Of course, you could always just delete the 
connection and create a new one. However, the following steps show you a quicker 
way to do this. 

To move either end of a connection, do the following: 

1. Select the connection. 

2. Move the mouse pointer over either selection handle that appears on the ends of 
the connection. 

3. Press and hold mouse button 2. 

4. Move the mouse pointer to the new part or connection. 

5. Release the mouse button. 

Depending on the connection type, you may get a pop-up menu asking you for new 
information for the connection. 

What you can change 

You can change the source and target of either end of any connection. However, 
depending on the feature that you connect to when you make the change, you might 
get a different type of connection than the one you started with. 

The following table gives you a closer look at the connection types and what you can 
change without changing the connection type: 

Connection type Move either end Move source end Move target end 

attribute-to-attribute x 
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Connection type 

Move either end 

Move source end 

Move target end 

attribute-to-member 

function 


X 


attribute-to-action 

X 



event-to-action 

X 



event-to-attribute 

X 



event-to-member function 


X 


custom logic 

X 



parameter connection 

X 




Making Connections for the OASearch Application 


The following sections show you how to connect the parts that were used to create a 
GUI for the OAContractView part in “Constructing a GUI: the OASearch 
Application” on page 161. 

Enabling Push Buttons When an Entry Field Contains a Value 

This section shows you how to make the connections that enable the Refresh and 
Save push buttons in the OAContractView window. When you have made these 
connections, the window appears as shown in Figure 84. 



Figure 84. ContractView Window with Variable and Push Button Connections 
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Follow these steps to enable the push buttons: 

1. From the Account Number pop-up menu, select Connect. 

2. Select text from the list. 

3. Click on the Refresh push button. 

4. Select enabled from the pop-up menu. 

This connection means that the Refresh push button will only be enabled 
whenever the contents of the Account Number text changes, whether by typing 
text in it or by another connection. Here, you use an attribute-to-action 
connection because you want the enabled action to occur whenever the value of 
the text attribute changes. 

5. Follow the same procedure to connect the text attribute of the Account Number 
text part to the enabled attribute of the Save push button part. 

Enabling a Window to be Cleared of All Entry Values 

You can enable the Clear push button to empty all entry fields of their contents using 
more than one method. One way would be to connect the buttonClickEvent feature of 
the Clear push button to the removeAll action of each entry field in the window. 
Another way would be to connect the buttonClickEvent feature of the Clear push 
button to a resetFields member function of the OAContractView composite part. 

For this example, assume that the member function has been written. Make the 
connection as follows: 

1. From the Composition Editor, use Alt-mouse button 2 to select the 
buttonClickEvent of the Clear push button. 

The connection spider appears. 

2. Use Alt-mouse button 2 to select an empty section of the free-form surface. 

3. Select More from the pop-up menu. 

4. Enter the member function declaration in the entry field as shown in Figure 85 
on page 206. 
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[SI Event-to-member-function connection - Settings 


ClearPBI Event name: buttonClickEvent 
Select or enter the member function signature: 
For class OAContractorView 
Access public - 

void resetFieldsQ 


resetFieldsQ 


b--j 


Cancel 

1___ 

Delete Set parameters... Help 



Figure 85. Free-form Surface Connection Dialog 

5. Select the OK push button. 

6. Switch to the Class Editor. 

Include the files containing the member function code. For this example, the file 
names are oafwclr.cpv and oafwclr.hpv. 

a. In the User .hpv file field, type the name of the header file, oafwclr.hpv 

b. In the User .cpv file field, type the name of the code file, oafwclr.cpv 

For details on the attributes, actions, or events of a particular part, refer to the Visual 
Builder Parts Reference. For more information on how to perform these operations, 
see “Making the Connections” on page 175. 

Connecting the Variable Part 

Once you have added the variable to the free-form surface and set its name and type, 
you need to connect it to the OAContractView composite part. 

Making the attribute-to-attribute connections 

So that recruiters can display and update contract information held by the Contract 
variable, you must make attribute-to-attribute connections between the composite 
visual part and the Contract variable as follows: 
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From part, feature 

To part, feature 

Contract, #accoun tNum 

EntryField 1 ,#text 

Contract ,#companyName 

EntryField2,#text 

Contract ,#projectMgr 

EntryField3 ,#text 

Contract ,#deptName 

EntryField4,#text 

Contract ,#positionTitle 

EntryField5 ,#text 

Contract ,#startDate 

EntryField6,#text 

Contract ,#endDate 

EntryField7,#text 

Contract ,#currContractor 

EntryField8,#text 

So far, the connections appear as 

shown in Figure 86. 



Figure 86. ContractView with Attribute-to-Attribute Connections 

Making the event-to-action connections 

To enable push buttons on the composite visual part, you must make event-to-action 
connections. This is a two-step process, because you specified an input parameter for 
each of the data access actions. First, connect each push button to the Contract 
variable. The connection line appears dotted, indicating an incomplete connection. 
Next, connect the attribute that represents the input parameter to the event-to-action 
connection itself. 
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For this example, make the following connections: 


From part, feature 

PushButton 1 ,#button ClickEven t 
EntryFieldl (Account Number text) 


To part, feature 

Contract MgetContract 

The anAccountNum parameter of 
the 

PushButton 1 ,#buttonClickEvent—> 
Contract ,#getContract connection. 
Visual Builder draws the parameter 
connection in the opposite 
direction. 


PusbButton2,#buttonClickEvent Contract ,#putContract 

EntryFieldl ,#text (Account Number text) The anAccountNum parameter of 

the 

PushButton2 ,#buttonClickEvent—> 
Contract ,#putContract connection. 
Visual Builder draws the parameter 
connection in the opposite 
direction. 


The connections now appear as shown in Figure 87. 



p] 

Contract 


Figure 87. OAContractView with Event-to-Action Connections 
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The putContract and getContract actions throw exceptions when the account number 
is not found in the database. 

Passing Exceptions to Message Boxes 

You can trigger the display of a message box when an exception is thrown. Although 
a message box is a user-interface element. Visual Builder treats message boxes as 
nonvisual parts. 

Adding the message box 


To add a message box to the free-form surface, select 



, the Other category. 


from the parts palette; then add 
surface. 



an IMessageBox* part, to the free-form 


Making the connections 

Now, connect the exceptionOccurred event of each event-to-action connection to the 
showException action of the message box. 

The connections appear as shown in Figure 88 on page 210. Save and close your 
visual part. 
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Figure 88. ContractorView with Exception Connections 
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Displaying Objects in a List Box 


In Chapter 2, “Creating a Simple Visual Builder Application” on page 7, you use an 
IListBox* part to display the items in a to-do list. The items that you put in the 
IListBox* part are text strings that you create by entering them in an entry field and 
clicking on a push button. In this case, the text strings displayed in the list box are 
just text strings. 

Besides viewing a list of text strings, you can also use a list box to view a collection 
of nonvisual objects. List boxes that can display objects include the following: 

• ICollectionViewListBox* 

• ICollectionViewComboBox* 

By connecting a collection of objects, such as an IVSequence* part, to one of these 
list boxes, you can view a collection of objects instead of simple text strings. 

The procedure outlined in this section modifies the original To-Do List application so 
that the list box contains objects rather than text strings. In this case, text strings are 
again displayed in the list box, but this time they are used to show the names of the 
objects in the sequence. When you select an item in the list box after completing this 
procedure, you are really selecting an object in the sequence, not the text string that 
represents the object. 

The modified To-Do List application differs from the original application in that it 
uses the following parts: 

• An ICollectionViewListBox* part instead of an IListBox* part. 

The ICollectionViewListBox* part can contain objects instead of just text strings. 

• An IVBFactory* part. 

The IVBFactory* part creates new objects to put in the list box. 

• An IVSequence* part. 

The IVSequence* part contains the sequence of objects that is reflected in the list 
box. 

• A ToDoItem part. 

ToDoItem is a nonvisual part that is used as the type of objects that the list box 
and sequence will contain, and that the object factory will create. 

The following prerequisites must be met to reflect a sequence of objects in a list box: 
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• The class name of the type of objects in the list box and sequence, as well as the 
type of objects that the object factory creates, must be the same. This class name 
must also be the name of a part that inherits from IStandardNotifier. It does not 
have to inherit from IStandardNotifier directly, but IStandardNotifier must be 
somewhere above it in its class hierarchy. 

• The objects in the sequence must override the asString member function inherited 
from the IVBase part. This is necessary so that at least one attribute of each 
object, such as the object’s name, can be displayed in the list box. 

In the procedure that you will follow for the To-Do List application, the 
ToDoItem nonvisual part has its own asString member function. This member 
function overrides the asString member function of IVBase by calling the 
toDoItemName attribute’s get member function, which returns the name of the 
to-do item, as follows: 

IString ToDoItem :: asString () const 

{ 

return toDoItemName(); 

} 


The following steps show you how to modify the original To-Do List application to 
use objects instead of text strings. If you have not already done so, please complete 
the original application, shown in Chapter 2, “Creating a Simple Visual Builder 
Application” on page 7, before continuing with this example. 

Making a copy of the ToDoList part 

1. Select todolist.vbb. 

Visual Builder displays the name of the ToDoList part in the Visual Parts list 
box. 

2. Select the ToDoList part. 

3. Select Part^Copy. 

Visual Builder displays the Copy Part window. 

4. Enter ToDol_st2 in the Target part name field. 

5. Enter todolst2.vbb in the Target file name field. 

6. Select the Copy push button. 

Visual Builder creates a copy of the ToDoList part, gives it the name ToDoLst2, 
and stores it in the todolst2.vbb file. 
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Creating the ToDoItem non visual part 

1. Open a new nonvisual part by doing the following: 

a. In the Visual Builder window, select Part-»New. 

Visual Builder displays the Part — New window. 

b. Fill in the fields in this window as follows. 

Class name ToDoItem 

Description Type of objects in To-Do List 

File name ToDoLst2.vbb 

Part type Nonvisual part 

Base class IStandardNotifier 

c. Select the Open push button. 

Visual Builder displays the Part Interface Editor. 

2. Create a new attribute called toDoItemName by doing the following: 

a. On the Attribute page, fill in the following fields: 

Attribute name toDoItemName 

Attribute type IString 

b. Select the Add with defaults push button. 

Visual Builder adds the toDoItemName attribute to the ToDoItem part. 


You can add the toDoItemName attribute to the preferred features list so 
that it will be readily available for making connections by doing the 
following: 

1. Switch to the Part Interface Editor. 

2. Select the Preferred page. 

3. Scroll down the list of attributes until you find the toDoItemName 
attribute and select it. 

4. Select the Add» push button. 

Visual Builder adds the toDoItemName attribute to the list of preferred 
features so that it will appear in the pop-up connection menu. 


3. Specify the .hpv and .cpv files for Visual Builder to use for the default feature 
code for the toDoItemName attribute by doing the following: 

a. Switch to the Class Editor if you followed the steps in the preceding hint. 
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b. Fill in the following fields: 

User .hpv file ToDoItem.hpv 
User .cpv file ToDoItem.cpv 

4. Generate the default source and feature code for the ToDoItem part by doing the 
following: 

a. Select File^Save and generate^Part source. 

Visual Builder generates the code for the ToDoItem part and stores it in files 
named ToDoItem.hpp and ToDoItem.cpp. These files contain the appropriate 
include statements for the ToDoItem.hpv and ToDoItem.cpv files. 

b. Select File^Save and generate-^Feature source 

Visual Builder generates the default code for the toDoItemName attribute and 
stores it in the ToDoItem.hpv and ToDoItem.cpv files. 

5. Override the asString member function in the IVBase* part by doing the 
following: 

a. Using your favorite text editor, edit the ToDoItem.hpv file and insert the 
following at the bottom of the public section: 

IString ToDoItem :: asString () const; 

b. Save the file. 

c. Edit the ToDoItem.cpv file and insert the following at the bottom of the file: 

IString ToDoItem :: asString () const 

{ 

return toDoItemName(); 

} 

d. Save the file and close the text editor. 

6. Close the Part Interface Editor. 

The ToDoItem part is now completed. 

Replacing IListBox* with ICollectionViewListBox* 

1. Open the ToDoLst2 part. 

2. Delete the IListBox* part. 

The IListBox* part only accepts strings. You want a part that accepts objects. 

Visual Builder displays a message warning you that it will delete the connections 
as well as the list box if you continue. You want to delete the connections 
because you need different connections for this example. 
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3. Select the OK push button. 

Visual Builder deletes the list box and the connections. 


4. Select 


m 


, the Lists category, from the row of icons on the left-hand side 


of the parts palette. 


5. Select 


, the ICollectionViewListBox* icon, from the row of icons that 


Visual Builder displays on the right-hand side of the parts palette. 

6. Place the crosshairs below the bottom left corner of the second static text part 
and click mouse button 1. 


A list box part that displays the items in a collection is placed beneath the second 
static text part. 


Specifying the type of items the list box can contain 

1. Move the mouse pointer to the list box, click mouse button 2, and select Open 
Settings. 

Visual Builder displays the settings notebook for the list box. 

2. Enter ToDoItem* in the Class name of items field. 

3. Select the OK push button. 

The list box can now accept only ToDoItem* objects. 


Placing an IVBFactory* part on the free-form surface 


1. Select 





, the Models category, from the row of icons on the left-hand 


side of the parts palette. 


-M 

2. Select !_*-*-*-* I , the IVBFactory* icon, from the row of icons that Visual 
Builder displays on the right-hand side of the parts palette. 

3. Place an object factory part on the free-form surface to the right of the To-Do 
List window adjacent to the entry field. 

4. Change the text beneath the object factory icon to ItemFactory. 
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Specifying the type of objects the object factory can create 

1. Move the mouse pointer to the object factory, click mouse button 2, and select 

Change Type. 

Visual Builder displays a window in which you are to enter the type of objects 
that the object factory is to create. 

2. Enter ToDoItem* in the entry field in this window. 

3. Select the OK push button. 

The object factory can now create only ToDoItem objects. 

Placing an IVSequence* part on the free-form surface 

1. Select Options-*Add part. 

Visual Builder displays the Add part window. 

2. Enter ItemSequence in the Name field. 

3. Enter IVSequence* in the Part class field. 

4. Select the Add push button. 

5. Place an IVSequence* part on the free-form surface surface to the right of the 
To-Do List window adjacent to the list box. 

Specifying the type of objects in the sequence 

1. Move the mouse pointer to the sequence, click mouse button 2, and select Open 
Settings. 

Visual Builder displays the settings notebook for the sequence. 

2. Enter ToDoItem* in the Class name of items field. 

3. Select the OK push button. 

The sequence can now accept only ToDoItem objects. 

Making the new connections 

The following steps describe the connections that this example requires to add objects 
to and remove objects from the list box. To review the instructions for connecting 
features, see “Making the Connections” on page 175. 

1. Connect the buttonClickEvent feature of the Add push button to the new action of 
the object factory. 

This connection causes the object factory to create a new ToDoItem object 
whenever a user clicks the Add push button. 
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2. Connect the toDoItemName attribute of the object factory to the text attribute of 
the entry field. 

This connection causes text in the entry field to be used as the name of 
ToDoItem objects that the object factory creates. Notice that the connection line 
is violet, the color of a parameter connection, instead of cyan, which is the color 
of an attribute-to-attribute connection. The connection line is violet because the 
text attribute of the entry field supplies a value for the toDoItemName attribute 
only when the object factory creates a new object, just as if it were satisfying a 
parameter of the new action. 

3. Connect the newEvent attribute of the object factory to the addAsLast action of 
the sequence. 

This connection causes each new ToDoItem object to be added as the last object 
in the sequence. 

4. Connect the this attribute of the sequence to the items attribute of the list box. 

This connection causes the list box to display all of the ToDoItem objects that 
the sequence contains. 

5. Connect the buttonClickEvent feature of the Remove push button to the 
removeAtPosition action of the sequence. 

This connection causes the object at a specified position in the sequence to be 
removed. This connection is incomplete because the removeAtPosition action’s 
position parameter must be satisfied. 

6. Connect the position parameter of the previous connection to the 
selectedCollectionPosition attribute of the list box. 

This connection provides the position of the selected item in the collection of 
objects, which is required by the previous connection in order to remove an 
object. 

Generating the source code for your visual part 


To generate the C++ source code for your visual part, select File-*Save and 
Generate-*Part source. Visual Builder generates the following files in the working 
directory: 


todolst2.cpp 

todolst2.hpp 

todolst2.h 

todolst2.rc 


The C++ code for your todolst2 part. 

The C++ header file for your todolst2 part. 

The resource header file for your todolst2.cpp file. 
The resource file for your todolst2.cpp file. 
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Generating the source code for your mainQ procedure 

To generate the source code for your main() procedure, select File^Save and 
Generate^main() for part. Visual Builder generates the following files in the 
working directory: 

todolst2.app The main function for your application. 

Note: If you start Visual Builder from a WorkFrame project, the 
name of this file is vbmain.cpp. 

todolst2.mak The make file that you specify when you build your application. 

Note: You must select Options—» Generate make files in the 
Visual Builder window to generate this file. 


Building the new To-Do List application 


1. Open an OS/2 window. 

2. Change to your Visual Builder working directory. 

3. Enter the following command: 
nmake todolst2.mak 


This command produces the following files: 


todolst2.exe 

todolst2.map 

todolst2.o 


todolst2.obj 


todolst2.res 


The executable file for your application. 

The application configuration map. 

The object file for your application. 

Note: If you start Visual Builder from a WorkFrame project, 
the name of this file is vbmain.obj. 

The object file for your part. Visual Builder provides a 
separate object module for your part that is used when 
compiling this part with other parts. 

The binary resource file that is bound to todolst2.exe. 


Running the new To-Do List application 


To run your application from the same OS/2 command prompt from which you 
entered the nmake command, enter the following: 

todolst2 


Once your application is running, experiment with it to make sure it works as you 
designed it. That is all there is to it! 
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You can add a finishing touch to your application by creating an OS/2 program 
object. Create a program object from the OS/2 Templates folder, specifying the name 
todolst2.exe as the program name and the directory that contains todolst2.exe as the 
working directory. Once you have done this, you can run your application by simply 
double-clicking on the program object you just created. 
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Creating Resizable Windows 


The purpose of this chapter is to show you how to use multicell canvases to build a 
window that can be resized dynamically. 

All visual parts of the OASearch sample application except OAContractorView use 
multicell canvases as client areas. (OAContractorView uses multicell canvases as 
notebook page clients.) The example built in this chapter is based on Figure 89. 
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Figure 89. Completed OAContractView Window with Multicell Canvas 


For the finished panel, see the OAContractView part in oawin.vbb. 


What Are the Benefits of Using a Multicell Canvases? 

Because multicell canvases are dynamically resizable, they are the best canvas choice 
for applications that will be used in a variety of display resolutions. Using multicell 
canvases also makes it easier to plan for translation of your interface into other 
languages. 

Multicell canvases contain rows and columns of cells into which you can drop parts. 
Cells are referred to by row and column location: the cell at row 2, column 3 is 
called cell (2,3). Each cell is initially very small, 10 pixels wide and 10 pixels high. 
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A grid of 5 rows and 5 columns appears when you first drop a multicell canvas into a 
client area. 

Any extra space between the grid and the bounds of the client area appears to the 
right of the rightmost grid line and below the bottommost grid line. This extra space 
is called the expansion area. The expansion area can also change size at run time 
when the user resizes the window. 

When you drop a visual part into the cell, the cell resizes to fit the minimum size of 
the dropped part. This minimum size is calculated for you based on limits that are 
set for the dropped part. 

For example, suppose you want an entry field that holds 10 characters. You drop the 
part and use the settings notebook to set its limit to 10 characters. The minimum size 
of the entry field is then calculated based on holding 10 characters of the font defined 
for the entry field. 

The minimum size of a cell also depends on the size of parts that span the cell but 
are not contained within it. For specific examples of how layout influences minimum 
size, refer to the sample visual parts contained in oawin.vbb. 

Rows and columns are either fixed or expandable, depending on how their size is 
calculated. 

• The size of a fixed row or column is based on the minimum size of the largest 
cell in that row or column. If no part occupies a cell in that row or column, the 
row or column takes the default minimum size. 

• Expandable rows or columns can grow from their minimum size (the same as if 
their size were fixed) to include the expansion area. If two or more expandable 
rows or columns exist, the expansion area is parceled out among them. 

Examples of the use of expandable columns appear in oawin.vbb. 

When first created, all rows and columns have a fixed size. To make them 
expandable, edit the settings for the multicell canvas. For more information, see 
“Changing the Settings for a Multicell Canvas” on page 231. 

Working with multicell canvases does not require the Visual Builder alignment tools. 
You alternate between the free-form surface and the settings notebook for the 
multicell canvas. 
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Adding a Multicell Canvas 

This example is based on OAContractView, found in oawin.vbb. The finished part is 
shown in Figure 89 on page 221. 

1. Because you are constructing a new user interface, begin by creating a visual 

part. Call it contractView. 

When you create a visual part, the Composition Editor opens and an 
IFrameWindow* part is automatically added for you. By default, the client area 
of the IFrameWindow* part appears as a canvas. 

2. Delete the default canvas client. 


3. Select 


4. Select 


SI 


, the Composers category, from the left side of the parts palette. 


aa 


, the IMultiCellCanvas* part, from the right side of the parts 


palette and drop it on the IFrameWindow* part. 


Your visual part now looks like Figure 90. 


FrameWindow 



Figure 90. New contractView Part with Empty Multicell Canvas 
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Adding Parts to the Multicell Canvas 

When you first drop a multicell canvas, the cell grid appears at its default size in the 
upper-left corner of the client area. You can now drop parts into the canvas. For the 
contractView example, do the following: 


1. Select 


, the Data Entry category, from the left side of the parts palette. 


A A 

2. Select J i, , the IStaticText* part, from the right side of the parts palette. 
When you move the mouse pointer over the free-form surface, the pointer 
changes to crosshairs. 

3. Drop the part at cell (2,2) of the multicell canvas. 

Row 1 was left as a spacer between the top of the multicell canvas and the 
window border. When you drop the IStaticText* part, cell (2,2) expands to 
contain the dropped part. The multicell canvas now looks like Figure 91. 



Figure 91. Multicell Canvas with IStaticText * Part at Cell (2,2) 

4. Drop another IStaticText* part at cell (4,2), leaving row 3 as a spacer. The 
multicell canvas now looks like Figure 92. 
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Figure 92. Multicell Canvas with IStaticText * Parts, Showing Spacer Rows 

5. Drop two more IStaticText* parts into the expansion area below the StaticText2 
part. 

Each time you drop a part into the expansion area, a new row is created for you. 
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6. Drop three more IStaticText* parts in column 3 as shown in Figure 93 on 
page 225. 
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Figure 93. Multicell Canvas Showing Parts Dropped into an Expansion Row 


No spacer rows exist yet between these new rows. We will add these in “Adding 
Rows or Columns Using the Contextual Menu” on page 226. Now add some 
IEntryField* parts. 


7. 



the Data Entry category, from the left side of the parts palette. 


8. Select ll 


, the IEntryField* part, from the right side of the parts palette. 


9. Drop IEntryField* parts in the expansion area to the right of the IStaticText* 
parts, starting at row 2. A new column 6 is created, as shown in Figure 94. 
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Figure 94. Multicell Canvas Showing Parts Dropped into an Expansion Column 
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Changing the Multicell Canvas Grid 

You can add or delete rows or columns from a multicell canvas as follows: 

• To add rows or columns from the expansion area, you can just drop parts into it, 
as discussed in “Adding Parts to the Multicell Canvas” on page 224. 

• To add several rows or columns at a time, you might find it easiest to change the 
grid using the multicell canvas’s settings notebook. This method is discussed in 
“Adding Rows or Columns Using the Settings Notebook” on page 233. 

• With the multicell canvas selected, you can press mouse button 2 and use the 
contextual menu. 

Adding Rows or Columns Using the Contextual Menu 

You can add rows or columns anywhere on the multicell canvas as follows: 

1. Select a cell next to where you want to add the row or column. 

Note: No selection handles are shown on the cell if it is empty. Also, you can 
only open the contextual menu for an empty cell. 

2. Press mouse button 2 to open the contextual menu. 

3. To add a row, select Rows. To add a column, select Columns. 

A cascade menu appears. 

4. If you want to insert the row above the cell you selected, select Add row before 
from the cascade menu. 

If you want to insert the row below the cell you selected, select Add row after 
from the cascade menu. 

For columns. Add column before inserts a column to the right of the selected 
cell. Add column after inserts a column to the left of the selected cell. 

For practice, add spacer rows to the contractView example as follows: 

1. Select the empty cell to the left of StaticText3. Add a row after it. 

2. Add one row each after StaticText4 through StaticText7. 

At this point, the contractView window looks like Figure 95 on page 227. 
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Figure 95. Multicell Canvas with Inserted Rows 


Deleting Rows or Columns Using the Contextual Menu 

You can delete rows or columns from anywhere on the multicell canvas as follows: 

1. Select a cell in the row or column you want to delete. 

2. Press mouse button 2 to open the contextual menu. 

3. To delete the row, select Rows. Then select Delete row. 

To delete the column, select Columns. Then select Delete column. 


Extending a Part to Span More than One Cell 

Parts can span more than one column or row. This is necessary when placing a part 
entirely within one cell would distort the multicell canvas. Consider what happens 
when you add three push buttons individually to the sample multicell canvas, as 
shown in Figure 96 on page 228. 
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Figure 96. Distorted Multicell Canvas with Individual Push Buttons 


Clearly, this was not intended. Instead, build a deck of push buttons using an 
ISetCanvas* part as a base, as follows: 

1. Drop an ISetCanvas* part in the bottom expansion area of column 2. 

2. Extend the span of the ISetCanvas* as follows: 

a. Select the ISetCanvas* part. 

b. Holding the Alt key with one hand, drag either right-hand part handle over to 
the column that contains the IEntryField* parts. 

c. Release the mouse. The sample window now looks like Figure 97. 
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Figure 97. Multicell Canvas with ISetCanvas* Spanning Several Cells 

3. Add three IPushButton* parts to the ISetCanvas* part. 
228 Visual Builder User’s Guide 














Developing Applications 
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The ISetCanvas* and multicell canvas parts expand to contain the newly dropped 
IPushButton* parts. 

To change the way minimum size is calculated for the IPushButton* parts, 
edit Pack Type settings for the ISetCanvas* part. 


4. Edit the IStaticText* parts so that they appear as shown in Figure 89 on 
page 221. Extend each column 2 IStaticText* part into column 3. 


Adding a Group Box 

To organize groups of related visual parts on the multicell canvas, add a group box. 
You can drop the IGroupBox* part before or after you drop the visual parts contained 
within it. 

• If you prefer to drop the IGroupBox* part first, consider carefully how many 
rows and columns you need within the group box. Add any extra rows and 
columns before you drop the IGroupBox* part. It can be difficult to add others 
in the correct locations later. 

• If you prefer to drop the contained parts first, you must edit tabbing and depth 
order after you have dropped the IGroupBox* part. This is necessary because 
parts are added to the window’s tabbing and depth order in the order in which 
they are dropped. To work properly, the IGroupBox* part must appear in the 
tabbing and depth order before the parts contained within it. 

In the contractView sample, the column 3 IStaticText* parts and their entry fields 
belong to the Position Details group shown in Figure 89 on page 221. 

The group box will extend from cell (10,2) to cell (18,8). 

Adding the extra rows and columns to hold the group box 

Extra cells are necessary to hold the group box and provide space between the group 
box and the parts within it. 

1. Add 2 rows above Title. 

2. Add 2 rows after Contractor. 

3. Add 2 columns after the corresponding IEntryField* parts. 

The sample window now looks like Figure 98 on page 230. 
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Figure 98. Preparing the Multicell Canvas to Hold an IGroupBox* Part 


Dropping and extending the group box 


1. Select 


, the Data Entry category, from the left side of the parts palette. 


2. Select 


the IGroupBox* part, from the right side of the parts palette. 


3. Drop the IGroupBox* part into cell (10,2). 


This temporarily distorts the multicell canvas. Resize the IFrameWindow* part 
to see the extra columns on the right. 


4. Select the IGroupBox* part. Holding the Alt key with 1 hand, drag the lower 
right part handle to cell (18,8) as shown in Figure 99 on page 231. 
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Figure 99. Multicell Canvas Showing Dragged IGroupBox* Part 

If necessary, press Alt-Backspace to undo and retry. Edit the IGroupBox* text to 
read Position Details. Remember to move the IGroupBox* part up in the tabbing 
and depth order. 


Changing the Settings for a Multicell Canvas 

You can use the General page of the multicell canvas settings notebook to do the 
following: 

• Move a dropped part 

• Change the default minimum size for rows or columns 

• Add rows or columns 

• Delete rows or columns 

• Make fixed rows and columns expandable 

This page consists of a series of directly editable tables. 

Moving Dropped Parts 

From the free-form surface, you can move dropped parts by selecting and dragging 
them to their new locations. You can also move dropped parts between cells in a 
multicell canvas using the settings notebook as follows: 

1. Open settings for the multicell canvas. 

2. At the top of the General page is a scrollable list of all parts contained in the 
multicell canvas as shown in Figure 100 on page 232. 
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Figure 100. Multicell Canvas General Settings, Controls Table 

3. Select the table entry you want to change and edit the highlighted value. Row 
and column numbering starts from (1,1) in the upper-left corner of the multicell 
canvas. 

4. Select the OK push button to close settings. 

Use this table for reference whenever you edit row and column settings. 

Changing Default Minimum Size for Rows or Columns 

You can change the minimum size of a row or column when it is empty. As stated 
previously, the default minimum size is 10 pixels wide (columns) and 10 pixels high 
(rows), but you can change the default minimum size for individual rows and 
columns as follows: 

1. Open settings for the multicell canvas. 

2. The second table on the General settings page is called Rows, as shown in 
Figure 101. 
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Figure 101. Multicell Canvas General Settings. Rows Table 

3. The default height appears as nil. To change the minimum height for row 1, 
select the Row 1 table entry under Height. Change this to the new default value 
in pixels. For example, the minimum height of row 1 in most views of the 
OASearch sample application is 20. 
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4. Scroll down the General page a little more to see the third table on the page, 
called Columns. You can edit values in this table in the same way you edited 
the Rows table. 

5. Select the OK push button to close settings. 

Adding Rows or Columns Using the Settings Notebook 

To save time when adding more than one row or column at a time, use the settings 
notebook. The methods for adding rows and columns are similar, as follows: 

1. Open settings for the multicell canvas. 

2. If necessary, scroll down to the Rows table. For a complex layout, consider 
resizing the window so that the Controls table is also displayed. 

3. Select the number of a row next to the insertion point. Select the Add push 
button. 

4. Select either Add before or Add after. 

• Add before inserts the new row above the selected row. 

• Add after inserts the new row below the selected row. 

5. Select the OK push button to close settings. 

Deleting Rows or Columns Using the Settings Notebook 

To save time when deleting more than one row or column at a time, use the settings 
notebook. The methods for deleting rows and columns are similar, as follows: 

1. Open settings for the multicell canvas. 

2. If necessary, scroll down to the Rows table. For a complex layout, consider 
resizing the window so that the Controls table is also displayed. 

3. Select the number of the row you want deleted. Select the Delete push button. 

4. Select the OK push button to close settings. 

Making Rows or Columns Expandable 

To allocate extra client space, make at least one row and one column expandable. In 
most of the OASearch windows, the row immediately above the deck of push buttons 
is expandable. In the OAContractView part, the rightmost column is expandable. 

For a more complicated example involving several expandable rows and columns, see 
the OAMain part in oawin.vbb. 

The methods for making rows and columns expandable are similar, as follows: 

1. Open settings for the multicell canvas. 
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2. If necessary, scroll down to the Rows table. For a complex layout, consider 
resizing the window so that the Controls table is also displayed. 

3. The default expansion value appears as nil. Select the appropriate entry from 
the Rows table under Expand. For the contractView example, select the row 19 
entry. 

4. The value d is highlighted. Change it to y and select the Apply push button. 

5. Move the settings notebook window over so you can see the result of your work, 
as shown in Figure 102. 
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Figure 102. Multicell Canvas with Expandable Row 19 

The expansion area is now hidden. All extra vertical space becomes part of row 
19. 

6. When you are finished adjusting row and column expansion settings, select the 
OK push button. 

To make this row fixed later, enter n in the Expand column. 
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Constructing Containers and Notebooks 


The purpose of this chapter is to show how easy Visual Builder makes it to use IBM 
Open Class Library container and notebook controls. 

Container controls hold objects; for example, an OS/2 program folder holds program 
objects. You can display containers in different views including the following: 

• Icon view, like an OS/2 program folder. Container objects appear inside the 
container as icons. 

• Details view. Attributes of container objects appear in tabular columns. To use 
this view, you must define the container columns as well as the container itself. 

• Tree view, for container objects that are related hierarchically. 

Notebook controls present related information on tabbed pages that the user can 
display sequentially or randomly. For an example of a notebook control, open any 
Visual Builder settings editor. 


Adding Container Parts 

In this section, you set up a container in the OASkillView part to hold the OASkill* 
objects returned as a result of a user’s skill query. The completed window looks like 
Figure 103 on page 236. 
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Figure 103. OASkillView Window 


This example is based on the OASkillView* part, found in oawin.vbb. Before 
constructing this new visual part, make sure that oanonvis.vbb is loaded into Visual 
Builder. 

1. Create a new visual part and name it OASkillView. 

A frame window and default canvas appear. 



, the Lists category, from the left side of the parts palette. 




3. Select L_U , the IVBContainerControl* part, from the right side of the parts 

palette and drop the part onto the default canvas. 

4. Change the container’s name to SkillCnr. 


5. Resize the container part as needed. 
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Setting Up the Container 

You set some container values in the container part and some in the container column 
part. Set the following values in the container part: 

• Title and title format 

• View style 

• Type of contained objects 

Set the following values in the container column parts: 

• Column title and width 

• Attribute to appear in the column 

• Vertical and horizontal separators 

• Whether contents can be changed by the user 

For information about container columns, see “Adding Container Columns” on 
page 238. 

Setting the container titles 

1. Open the settings notebook for SkillCnr. 

2. Specify the general settings. In the Title Attributes group, type Contractors 
Holding This Skill into the Title field. 

3. Select both Show title and Show title separator. 

4. Select the Left radio button for left title alignment. 

Specifying the container type and layout 

1. Select showDetailsView from the View type list box. 

2. Scroll down on the General page. In the Container Item Attributes group, 
type OASkill into the Part type field. 

3. Select contractorlD from the Text drop-down combination box. The Text field 
specifies which OASkill attribute would appear as text in the container’s icon 
view. 

4. The Icon field specifies the icon to be used for each item in the container. Type 
the following into the Icon field: 

#1 Dynamic LinkLibrary("cppov33r").1oadlcon(803) 

cppov33r.dll is the resource DLL containing the icons for this application, and 
803 is the resource ID for the skill icon that would appear in the container’s icon 
view. 

5. Select the Refresh container after changes check box. 

6. Select the OK push button to save and close the settings notebook. 
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Adding Container Columns 

Once you have added a container, add container columns. This is a good idea even if 
you intend for the container to be used mainly as an icon view. 


1 . 

2 . 


Select 


IB 


, the Lists category, from the parts palette. 


Select the Sticky check box. 


3. 

4. 


Select 



, the IContainerColumn* part, from the parts palette. 


Drop two IContainerColumn* parts on the SkillCnr part. 


Setting up the container columns 

1. Open up the settings notebook for the first container column. 

2. On the General settings page, type Contractor ID in the Heading text field. 

3. Specify the column’s width (in pixels) in the Width field. For this example, 
enter 200. 

4. Specify the OASkill attribute to appear in this column. Select the Use the Text 
attribute set in the container radio button because you want to display the same 
information in this container column that the container displays as text on the 
icon view. 

5. Set the container so that its elements cannot be changed by the user. Select the 
following from the Styles settings page: 

• For the readOnlyHeading style, select the On radio button. 

• For the readonly style, select the On radio button. 

6. Set a vertical separator for container column 1 only. For the verticalSeparator 
style, select the On radio button. 

7. Select the OK push button to close the settings notebook. 

Repeat this procedure for the second container column, adjusting the width of the 
column to fit. The second column is supposed to display the number of years of 
experience each contractor has for a certain skill, so use the following settings: 

• Select the Use an attribute from the part radio button 

• Choose yearsExp to populate the container column. 

• Do not add a vertical separator. 
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Filling the Container 

The easiest way to fill the container is to use a collection part. The OASkillView 
part uses an IVSequence* part named SkillList. Basically, you manage container 
objects through the collection and use a single connection between it and the 
container to load the contents of the collection into the container. 

Adding the nonvisual parts 

The OASearch application uses static parts that are actually found in OAMain part. 
All nonvisual parts in this view except SkillList are variables that will be connected 
later to the actual parts. 

1. Add an OASkill* part as a variable. Name it Skill. 

For help on how to do this, see “Adding a Variable to a Composite Part” on 
page 163. 

2. Add an OASkillBase* part as a variable. Name it SkillBase. 

3. Add an IVSequence* part. Name it SkillList. 

4. Add an IMessageBox* part to handle exceptions. 

Populating the collection 

The SkillBase part contains the action (getSkills) needed to populate the skill list. 
The getSkills action takes two parameters, a skill description and a sequence. Make 
the following connections: 

From To 

S\d\\,#skillName EntryField 1 ,#text 

PushButtonl ,#buttonClickEvent SkillBase.#getSkills 

S\d\\,#skillName The aSkillName parameter of the 

PushButton 1 ,#button ClickEvent—> 

S k i 1 1 B ase#getSkilIs connection 

SkillList,#f/zA The a List parameter of the 

PushButton 1 ,#button ClickEvent—> 

S k i 11B ase#getSkilIs connection 

To handle exceptions, connect the exceptionOccurred feature of the getSkills 
connection to the showException feature of the message box part. 
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Connecting parts to fill the container 

To fill the container, connect the this attribute of the SkillList part to the items 
attribute of the container. 


Adding Notebook Parts 

The purpose of this section is to guide you through using a notebook part to create 
the OAContractorView part. The completed window looks like Figure 104. 
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Figure 104. The Opportunities Abound Contractor Information Window 

The steps in creating a notebook are as follows: 

• Add the notebook and set it up. 

• Add notebook pages and set them up. 
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Adding the Notebook 

Before constructing this new visual part, make sure that oanonvis.vbb is loaded into 
Visual Builder. 


1. Create a new visual part. Call it OAContractorView. 

A frame window and default canvas appear. 

2. Delete the default canvas part from the frame window and resize the window as 
necessary. 


3. 

4. 


Select 


Select 


SI 

Q. 


, the Composers category, from the left side of the parts palette. 


the INotebook* part, from the right side of the parts palette and 


drop the part onto the frame window. 


Specifying the notebook layout 

You change the notebook’s appearance using its settings notebook. As you make 
selections, notice that the Preview area changes to reflect your choices. 

1. Open the settings notebook for the notebook part. 

2. On the General settings page, select the icon that represents the orientation that 


you want for the notebook. For this example, select 
group. 

3. From the Binding group, select the Spiral radio button. 

4. From the Tab Shape group, select the Round radio button. 

5. From the Justification group, select the two Center radio buttons. 

6. Select the OK push button to close the settings notebook. 


from the Layout 
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Adding Notebook Pages 

You add notebook pages using the notebook part’s Composition Editor contextual 
menu. 

1. To add the first page of the notebook, select Add initial page. 

2. To add each additional page, select Add page before or Add page after. 

For this example, add one page after the initial page. 


e 


Setting up the notebook page and tab 

1. Open the settings notebook for the first notebook page. 

To open the settings for the notebook page instead of the canvas that is on 
the notebook page, move the mouse pointer to the small area around the 
canvas before opening the settings. 


2. On the General page, type ContactPage into the Subpart name field. 

3. Type Contact into the Tab text field. This text is what appears on the notebook 
tab. 

4. Type Vital statistics into the Status text field. This text is what appears in 
the status area at the bottom of the notebook page. 

5. On the Style page, select the On radio button for the following styles: 

• The autoPageSize style, to enable automatic sizing of the notebook page 

• The statusText style, to enable display of the status text that you entered in 
the previous step to be displayed 

• The majorTab style, to give the notebook page a major tab 


Adding parts to a notebook page 


Each notebook page initially contains an ICanvas* part. If you want to use a 
different part, delete the ICanvas* part and select another part from the Composers 
category, such as IMultiCellCanvas*. 

Note: A notebook page allows only one subpart, which should be a part from the 
Composers category. You can, of course, add other subparts to the 
Composers part. 


The ContactPage subpart contains the primitive parts shown in Figure 105 on 
page 243. 
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Figure 105. OAContractorView General Page 

To see the other notebook pages, open the OAContractView part in oawin.vbb. 
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Adding Menus to Your Application 


The purpose of this section is to guide you through adding menus to the welcome 
window of the sample recruitment application. The completed menu parts and 
connections are shown in Figure 106. 



Figure 106. OASearch Welcome Window with Menus 


Types of Menus and Menu Items 

In Visual Builder, you use the same menu part to build several different menu types, 

as follows: 

Menu bars This menu type is attached to a window. It appears horizontally 
under the window’s title bar. 

Pop-up menus This menu type is attached to a control, such as an entry field, 

within the window. It appears vertically when the user selects the 
control and presses mouse button 2. 

Cascaded menus This menu type is attached to a cascade menu item. 

If the cascade menu item is part of a menu bar, the cascaded 
menu appears below the menu item as a pull-down menu. 
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If the cascade menu item is part of a pop-up menu, the 
cascaded menu appears beside the menu item. 
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Adding a Menu Bar 

Begin by opening the visual part that contains the OASearch welcome window, the 
OAMain part. 


1. Select 
palette. 




2. Select 


1 


, the Frame Extensions category, from the left side of the parts 


, the IMenu* part, from the right side of the parts palette and 
drop it on the free-form surface next to the window, as shown in Figure 107. 
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Figure 107. OAMain with Menu Part 

3. To add two of the menu choices to the menu bar, add two menu parts on top of 
the menu part for the menu bar. 

As you add each menu part, a cascade button part is added to the menu bar and a 
connection is made between the cascade button part and the menu part you 
added. This connection causes the menu part to be displayed when the user 
selects the cascade button part. See Figure 108 on page 247. 
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Figure 108. OAMain with Cascade Button Parts 

4. Edit the text of the menu choices as shown in Figure 106 on page 245. by 
selecting each one and pressing Alt-mouse button 1. 


Connecting the Menu Bar to the Window 

To make the menu a menu bar, connect the this attribute of the IMenu* part to the 
menu attribute of the window part. Although the menu continues to appear vertically 
on the free-form surface, this connection defines the menu part as a menu bar. 


e 


Since the menu bar is shown outside the frame window, be sure to leave 
enough space for it below the window title. 


Making this same connection to a part other than a window part, such as a list part, 
makes the menu part a pop-up menu instead of a menu bar. See “Types of Menus 
and Menu Items” on page 245 for more information. 


Adding Menu Choices 

Once the menu structure is complete, you need to add menu choices that do 
something other than open other menus. 


1. Select 
palette. 


, the Frame Extensions category, from the left side of the parts 
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2 . 

3. 


Select 


the IMenuItem* part, from the right side of the parts palette. 


The position at which you click the mouse is where the part is added within the 
menu. Drop menu items as follows: 


• One part as the last item in the Menul part 

• Four items in the Menu2 part 

• Two items in the Menu3 part 


You can change the position of a menu choice part within the menu part by using 
mouse button 2 to drag each item to a new position. Position these parts and change 
their text as shown in Figure 106 on page 245. 


Adding Menu Separators 

Once you have added and edited the OAMain menu items, add a separator bar to 
Menu2 between Skill and General Information as follows: 


1 . 


Select I 
palette. 



, the Frame Extensions category, from the left side of the parts 


2 . 


Ur. A... 



Select 

palette. 


the IMenuSeparator* part, from the right side of the parts 


Connecting Menu Choices to Actions 

Once you have added menu choices, you can connect them to actions in this or other 
parts. As an example, connect the Exit menu bar item so that when the item is 
selected, the main window closes, as follows: 

From part, feature To part, feature 

ExitMI ,#commandEvent FrameWindow,#c/ose 

Command events occur when a user selects a menu item, push button, or accelerator 
key. In this case, the user’ selection of Exit generates a command event to perform 
the close action on the Frame Window. 

Note: You cannot promote menu item events to the part interface. 
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The other menu choices shown in Figure 106 on page 245 connect to other parts that 
are not on this free-form surface. These connections are completed in “Completing 
the Menu Bar” on page 270. 
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Adding Help To Visual Builder Applications 


In this section, you leant about adding different types of help to your application. 

Generally, in application development, you develop your user interface and then 

provide the necessary help panels. The basic help types are as follows: 

Help Type Description 

Context-sensitive help Help information for the current choice, object, or 

group of choices or objects. The user can display 
context-sensitive help by tabbing or cursoring to a 
subpart and doing either of the following: 

• Pressing the FI key. You do not have to do 
anything to make this happen. Presentation 
Manager handles it for you. 

• Selecting the Help push button if you have 
provided one. See “Providing a Help Push Button” 
on page 258 for information on how to do this. 

General help Help for a specific window, explaining the purpose of 

the window and how it operates. 

To show you how to add help, we are going to write help for the main window of the 

OASearch application, introduced in Figure 24 on page 94. 



Figure 109. OASearch Welcome Window 
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The example we use in this chapter assumes that you have already built the main 
view for the OASearch application. If you want to do the example along with us, 
you must build this view first. 

The first step in providing help is to create the help file. 


Creating the Help File 

Before we can connect the help, we must first create the help file. 

Writing the help 

Using your favorite editor, create a new file and type in the following help source. 
Note: Be sure to use an .ipf extension when naming the file. 

:userdoc. 

:title.Opportunities Abound Databases Help 
:docprof toc=l Ctrl area=page. 

:ctrl Ctrlid=buttons controls= 'ESC SEARCH PRINT 1 page. 

:h1 res=9998. 

General Help for the Opportunities Abound Databases 
:il.general help 
rp.Text goes here. 

:hi res=9999. 

Request for Skill Information Help 

:i1.requesting skill information, help for 

rp.Text goes here. 

:hi id=10000. 

Skill Information Help 

til.skill information, help for 

rp.Text goes here. 

:h1 res=10OOl. 

Request for Contract Information Help 

:i1.requesting contract information, help for 

:p.Text goes here. 

:h1 res=100O2. 

Contract Information Help 

til.contract information, help for 

rp.Text goes here. 

:hi res=10OO3. 

Request for Contractor Information Help 

:i1.requesting contractor information, help for 

rp.Text goes here. 

:h1 res=10OO4. 

Contractor Information Help 

:i1.contractor information, help for 

rp.Text goes here. 

:euserdoc. 
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When creating your own help files, try using a Project Smarts IPF template, 
which provides the basic tags for creating online help using the OS/2 
Information Presentation Facility. For more information on writing online 
help, refer to the OS/2 Information Presentation Facility Guide and 
Reference. 

The :hl tags are heading tags. These tags cause IPF to create a new help panel using 
the text on the tag as the panel’s title. 

The res parameter specifies the panel’s resource number. See “Providing 
Context-sensitive Help’’ on page 254 to learn how these resource numbers are used. 

The :il tags are index tags. These tags allow you to provide an index of help topics 
for your application. If you provide a Help index choice in the Help pull-down 
menu on the menu bar, the user can select this choice to display the help index. 

When the user double-clicks on a topic in the help index, IPF displays the help panel 
whose :hl tag precedes the index tag in the help file. 

Save this file with a name similar to cppov33.ipf.ipf. 

Note: For convenience, we have provided the help source in the online version of 
this book, so you do not have to retype it. 

Building the help file 

Ensure that you have the IPF compiler installed on your system and that your 
environment variables are set up to run the IPF compiler. The IPF compiler comes 
with the OS/2 2.1 Toolkit and the OS/2 Warp Toolkit. 

To build the help file, simply run the Information Presentation Facility (IPF) 
compiler. For example, if you saved your help file with the name cppov33.ipf, you 
would enter the following command in the directory where you saved your file: 
ipfc cppov33.ipf 

This command generates a file called cppov33.hlp. 

You have now built your help file. The next step is to provide context-sensitive help 
in your application. 
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Providing Context-sensitive Help 

This section tells you how to provide context-sensitive help for subparts in your 
application. 

For this example, we use the graphic push buttons on the window. 

To provide context-sensitive help for a subpart, do the following: 

1. Open the cppov33.ipf file in your text editor and find the “Request for Skill 
Information Help” heading. 

Above this heading is the heading tag, :hl, with a res attribute. This attribute 
contains the resource number for the help panel for the Skills push button. 

2. Open the settings notebook for the subpart, in this case the Skill push button. 

See “Changing Settings for a Part” on page 140 if you need information on how 
to do this. 

3. Select the Control page. It looks like Figure 110. 


IBM push-button control with graphic (GraphicPushButtonl) - 


□ 



Figure 110. The Control Page of the Skill Push Button’s Settings Notebook 

4. Enter the resource number for the Skills push button help panel in the Help 
panel id field. 
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When you generate the code for your application. Visual Builder creates a help 
table in the resource (.re) file that it generates and inserts this number into the 
help table. 

5. If the Enable check box is not checked, select it. 

6. Select the OK push button. 

7. Repeat steps 2 through 6 for the Contract push button and the Contractor push 
button. Use the resource numbers for the “Request for Contract Information 
Help” and “Request for Contractor Information Help”, respectively. 

You have now provided context-sensitive help for the push buttons. The next step is 
to provide general help in your application. 


Providing General Help 

This section tells you how to provide general help for your application. For this 
example, we use the frame window. 

To provide context-sensitive help for your application, do the following: 

1. Open the cppov33.ipf file in your text editor and find the “General Help for the 
Opportunities Abound Databases” heading. 

Above this heading is the heading tag, :hl, with a res attribute. This attribute 
contains the resource number for the general information help panel. 

2. Open the settings notebook for the subpart, in this case the frame window. See 
“Changing Settings for a Part” on page 140 if you need information on how to 
do this. 

3. Select the Control page. It looks like Figure 111 on page 256. 
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Figure 111. The Control Page of the Frame Window’s Settings Notebook 

4. Enter the resource number for the general information help panel in the Help 
panel id field. 

When you generate the code for your application. Visual Builder creates a help 
table in the resource (.rc) file that it generates and inserts this number into the 
help table. 

5. If the Enable check box is not checked, select it. 

6. Select the OK push button. 

You have now provided general help for the main window. The next step is to 
provide a help window to display the help panels in. 


Providing the Application Help Window 

Now that you have added the context-sensitive help and the general help for the main 
window, you need a help window to display the help panels in. You must place an 
IHelpWindow* part on the free-form surface to give Visual Builder a window in 
which to display the help information. The default owner of the IHelpWindow* part 
is the primary part for your application. Therefore, no connections are required. 

To add a help window to your application, do the following: 
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1. Select 


the Other category, on the parts palette. 


2 . 

3. 


Select 



, the IHelpWindow* part, and place it on the free-form surface. 


Open the settings notebook for the IHelpWindow* part. See “Changing Settings 
for a Part” on page 140 if you need information on how to do this. It looks like 
Figure 112. 


IBM window for online help (HelpWindowl) - Settings 
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Figure 112. The Help Window’s Settings Notebook 

4. In the Title field, enter the title of the help window. 

This must be the same title that you entered on the :title tag in your .ipf file. 

5. In the Help libraries field, enter the name of the help file that you compiled, 
such as oasearch.hlp. 

If you had created multiple help files for your application, you would enter all of 
their names in this field. 

6. We recommend that you leave the Help table id field empty and let Visual 
Builder generate it for you unless you need a specific help table ID. Otherwise, 
you could have conflicts in your resource (.rc) file. 

7. Select the OK push button. 
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Associating Help Windows with Frame Windows Generated by an Object 
Factory 

You can associate a help window with a part that is generated by an object factory if 
the base class of that part is IFrameWindow*. To do this, you can do either of the 
following: 

• Edit the part that the object factory generates, place an IHelpWindow* part on 
the free-form surface next to it, and do all the things described in the preceding 
sections to use the help window properly. Repeat this step for each 
IFrameWindow*-based part that is generated by an object factory. 

You should use this method if you have created multiple help library (.hip) files 
for your library instead of putting all of your help panels in one library file. 

• Place an IHelpWindow* part on the free-form surface in the same view with the 
object factory if you have created only one help library file for all of your help 
panels. Then, do the following: 

1. Open the settings notebook for the IHelpWindow* part. 

2. Enter the help window title and the name of the library (.hip) file. 

3. Close the settings notebook by selecting the OK push button. 

4. Connect the newEvent feature of the object factory to the 
setAssociatedWindow action of the help window. 

5. Repeat step 4 for each object factory in the view. 

6. Edit each IFrameWindow*-based part that an object factory generates and 
specify the appropriate help panel IDs for the subparts that you want to 
provide help for. Each help panel ID must be a resource ID in the library 
file that you specified in step 2. 


Providing a Help Push Button 

The main window of the OASearch application, which we have been using for this 
help example, does not contain a Help push button. However, many applications 
provide such a push button to give users quick and easy access to the help 
information that the application provides. 


To provide a Help push button in your application, do the following: 


1. Select 
palette. 


0 


, the Buttons category, in the left-hand column on the parts 
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2. Select I I , the IPushButton* part, and place it where you want it to be. 

3. Change the text on the push button to Help. 

4. Open the settings notebook for the push button. 

5. Select the Styles tab. 

6. Find help on the Styles page and select the On radio button. 

This style turns a regular push button into a help push button. 

7. On the same page, find noPointerFocus and select the On radio button. 

This style keeps the Help push button from getting the input focus when a user 
clicks on it. By setting this style, you enable your application to display help for 
the part that has the input focus when a user clicks the Help push button. 
Otherwise, the user sees the help panel that you assign to the Help push button. 

When this style is set, the user must use the cursor keys to set the input focus on 
the Help push button. After doing this, the user can click on the Help push 
button to display the help panel that you assign to it. 

8. Select the OK push button to close the settings notebook. 

You now have a Help push button. If you have followed the steps in the preceding 
sections, clicking this button causes the contextual help panel for the part that 
currently has the input focus to be displayed. If no part has the focus, the main help 
panel for the window is displayed. The behavior of the Help push button is identical 
to that of the FI key. 

To provide a help panel for the Help push button itself, follow the instructions in 
“Providing Context-sensitive Help” on page 254. 


Displaying Fly-over Help When the Mouse Pointer Is Over a Part 

Another type of help that you can provide in your application is called fly-over help , 
which is intended to provide instant help for novice users. This type of help consists 
of a text string that your application displays when the user positions the mouse 
pointer over a subpart, such as a push button or list box. The text string should be 
short and precise, giving the user information such as the purpose of the subpart. 

Your application can provide the following types of fly-over help: 

• A short text string that your application displays next to the subpart that the 
mouse pointer is over 

• A longer text string that your application displays in a text control 
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Providing fly-over help for a subpart 


To provide fly-over help for a subpart, do the following: 

1. Place an IVBFlyText* part on the free-form surface by doing the following: 


a. Select 



, the Other category, on the parts palette. 


b. Select %| , the IVBFlyText* part, and place it on the free-form 

surface. 

2. Add fly-over help text to one or more subparts by doing the following: 

a. Open the settings notebook for a subpart, such as an entry field or push 
button. 


b. Select the Control notebook tab. 

c. Enter fly-over text strings in the Fly over short text field, the Fly over long 
text field, or both. 

Text that you enter in the Fly over short text field is displayed in a pop-up 
window next to a subpart when the user positions the mouse pointer over 
that subpart. 

Text that you enter in the Fly over long text field is displayed in a text 
control that you specify. For example, you might add an information area to 
a window and display the long fly-over help text there. See “Displaying 
Long Fly-over Text In an Information Area” on page 262 to see how this is 
done. 


O 


If one of your application views contains two or more frame windows, do 
not use the same IVBFlyText* part to assign long fly-over text strings to 
text controls in each window. If you do, your fly-over text probably will 
not appear in the window that you expect it to appear in. 

For example, suppose your view contains two frame windows: one that is 
displayed when your application starts and another one that is displayed 
when a menu item in the first window is selected. In this case, place two 
IVBFlyText* parts on the free-form surface. The first IVBFlyText* part is 
associated by default with the window that is displayed when your 
application starts. However, you must specify the owner of the second 
IVBFlyText* part by opening the IVBFlyText* part’s settings notebook and 
entering the name of the owner part in the Owner field, such as 
i FrameWi ndowl. 
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d. Select the OK push button to save the text strings that you just entered. 
That is all you need to do. There are no connections to make. 


Displaying Help in an Information Area 

There are times when it is helpful to provide an information area in an application 
window that your application can use to give the user feedback. For example, the 
information area might let the user know whether the application performed an 
operation successfully or it might provide a description of a menu choice. 

Visual Builder provides the IlnfoArea* part that you can use for this purpose. An 
information area is considered to be an extension of a frame window. You can only 
add it to an IFrameWindow* part. Visual Builder positions the information area at 
the bottom of the frame window’s client area. 


Adding an Information Area to a Frame Window 

To add an information area to a frame window, do the following: 


1 . 

2 . 

3. 


Select 




, the Frame Extensions category, on the parts palette. 


Select |> | , the IlnfoArea* part. 

Move the mouse pointer over the title bar or window border of the frame window 
and click mouse button 1. 


Visual Builder places an information area at the bottom of the frame window. 

4. Open the settings notebook for the information area. 

5. Enter text that you want your application to display in the following fields: 

Disabled text 

Text to display when the selected menu choice is disabled. 

Inactive text 

Text to display when no menu choice is selected. 

Missing text 

Text to display when the information area cannot find and display specific help 
for a menu choice. 
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Displaying Help for Menu Choices in an Information Area 

To display help text for menu choices in an information area, do the following: 

1. Create the menu bar and pull-down menus for your application. 

2. Open the settings notebook for each menu choice. 

3. Enter a description of the menu choice in the Info area text field. 

4. Select the OK push button to save the description you just entered. 

Displaying Long Fly-over Text In an Information Area 

Earlier in this chapter, we showed you how to add an IVBFlyText* part and display a 
short text string in a pop-up window. This section shows you how to display a 
longer text string in an IlnfoArea* part, although you can use any text control, such 
as an IEntryField*. 

To display a long fly-over text string in an information area, do the following. 

Note: The following steps assume that you have already added an IVBFlyText* part 
and an IlnfoArea* part to a frame window. If you have not, you should 
complete the steps in the following sections and then return here. 

• “Displaying Fly-over Help When the Mouse Pointer Is Over a Part” on 
page 259 

When following these steps, make sure you enter a text string in the Fly 
over long text field in the settings notebook for a subpart, such as an 
entry field or push button. 

• “Adding an Information Area to a Frame Window” on page 261 

1. Display the connection menu for the information area. 

2. Select the this attribute. 

3. Display the connection menu for the fly-over text part. 

4. Select the longTextControl attribute. 

That is all you have to do. 
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Displaying Information about Successful Actions In an Information Area 

One way to make your applications more user-friendly is to provide feedback to the 
user when an action or member function performs successfully, such as the successful 
completion of an action that is triggered by a buttonClickEvent feature. We 
recommend that you display this information in an IlnfoArea* part. 

To display information in an information area when an action or member function 
completes successfully, do the following: 

1. Create an event-to-attribute connection using the text attribute of the IlnfoArea* 
part as the target. The source event can be one of the following: 

• The same event that triggered the action or member function 

If the action or member function was triggered by an event, you can use the 
same event, such as the buttonClickEvent or commandEvent feature. In this 
case, be sure to check the connection order to make sure the event-to-action 
or event-to-member function connection occurs before the event-to-attribute 
connection. 

• The actionResult event of the connection that triggered the action or member 
function 

All connections have both an actionResult event and an actionResult 
attribute. Therefore, be sure you use the actionResult event as the source of 
the connection. 

2. Double-click on the connection you just made to open the settings window for 
the connection. 

3. Select the Set parameters push button to open the Constant Parameter Value 
Settings window. 

4. In the text field, enter the text string that you want to assign to the text attribute. 

Your application will display this text string in the information area each time the 
action or member function completes successfully. 

5. Select the OK push button to close the Constant Parameter Value Settings 
window. 

6. Select the Cancel push button to close the connection settings window. 
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Integrating Visual Parts into a Single Application 


In this chapter, you combine all visual parts of the OASearch sample application in 
preparation for generating code and compiling. This chapter includes the following 
tasks: 

• Adding nonvisual support parts to the primary part 

• Adding static visual parts 

• Adding visual parts as dynamic instances 

• Making the final connections 

To follow this example, load oanonvis.vbb and oawin.vbb into Visual Builder. 


Adding Nonvisual Support Parts to the Primary Part 

For this example, refer to the primary view, OAMain, in oawin.vbb, shown in 
Figure 113. 



Figure 113. Completed Opportunities Abound Databases Window 

1. Begin by building the primary part as you would any IFrameWindow*-based 
part. For information about building the menu bar, see Chapter 13, “Adding 
Menus to Your Application” on page 245. 

2. The OASearch application starts up with a small number of static nonvisual 
instances to support the visual parts. Add the following parts: 
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• OAContractor*. Name it Contractor. 

• OAContract*. Name it Contract. 

• OASkill*. Name it Skill. 

• OASkillBase*. Name it SkillBase. 

You must connect these part instances to the variables that represent them in the 
other visual parts. First, you must add the visual parts. 


Adding Static Parts 

One visual part, OAGenlnfo, exists statically in the OASearch application as a modal 
window. The disadvantage of using static visual parts is that once the user closes the 
window, the part is destroyed and cannot be instantiated again in the same session. 

Add the OAGenlnfo* part. Name it VBDevelopment. You must also connect 
OAGEnlnfo* to the menu item that causes it to display. For details, see “Completing 
the Menu Bar” on page 270. 


Adding Visual Parts as Dynamic Instances 

All OASearch visual parts except for OAMain and OAGenlnfo are created at run 
time as the user requests them from a menu or button selection. The dynamic 
windows are represented in the OAMain part by Object Factory parts. Like static 
visual parts, dynamic visual parts are destroyed when the user closes them. Flowever, 
the existence of the Object Factory enables the creation of a new instance of that 
same part the next time the user requests it. 

Like variable parts. Object Lactory parts are placeholders for other parts. Each 
Object Lactory part is set to the part it represents. The Object Lactory part works in 
tandem with a variable part that represents the dynamic part instance. You can use 
Object Lactory parts to create both visual and nonvisual parts. 

Unlike variable parts. Object Factory parts run the corresponding part class 
constructor, creating a new instance. Variable parts merely stand in for instances 
created elsewhere. 

Implementing dynamic parts involves the following tasks: 

• Adding and setting Object Factory parts 

• Adding variable parts 

• Connecting to the Object Factory parts 

• Connecting the Object Factory parts to the corresponding variable parts 
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Adding and Setting Object Factory Parts 

Before you can use Object Factory parts, you must have created the part classes to be 
represented. Before you start, be sure to load the .vbb files that contain those parts 
into Visual Builder. 


Adding the Object Factory parts 


1 . 

2 . 


Select 


n 


, the Models category, from the left side of the parts palette. 


Select the Sticky check box. 


-M 

3. Select l i LLL1 I , the Object Factory part, from the right side of the parts palette. 

4. Drop six Object Factory parts on the free-form surface. 


5. 


Unload the mouse pointer by selecting 
Visual Builder tool bar. 



, the Selection tool, from the 


Setting an Object Factory part 


1. Change the part name using the Composition Editor contextual menu. 

In the OASearch example, the Object Factory parts are named as follows: 


ConQFac 

ConVFac 

CtrQFac 

CtrVFac 

SklQFac 

SklVFac 


Request for Contract Information window 

Contract Information window 

Request for Contractor Information window 

Contractor Information window 

Request for Skill Information window 

Skill Information window 


2. Change the part type from the default (IStandardNotifier*) using the Composition 
Editor contextual menu. 


In the OASearch example, the Object Factory parts have the following types: 


ConQFac OAQueryContract* 

ConVFac OAContractView* 

CtrQFac OAQueryContractor* 

CtrVFac OAContractorView* 

SklQFac OAQuerySkill* 

SklVFac OASkillView* 


3. Set the Object Factory part to automatically delete each instance, as follows: 


Chapter 15. Integrating Visual Parts into a Single Application 267 



Developing Applications 


a. Open the settings notebook for the part. 

b. Switch to the General page. 

c. Select the AutoDelete check box. 

Adding Variable Parts 

When used with Object Factory parts, variable parts represent the newly created part 
instance. Add and set variable parts as follows: 

ContractQ Set the type to OAQueryContract*. 

ContractorQ Set the type to OAQueryContractor*. 

SkillQ Set the type to OAQuerySkill*. 

ContractV Set the type to OAContractView*. 

ContractorV Set the type to OAContractorView*. 

SkillV Set the type to OASkillView*. 

For more information on variables, see “Adding a Variable to a Composite Part” on 
page 163. 

Connecting to the Object Factory Parts 

Once you have added and set both the Object Factory and variable parts, connect the 
IGraphicPushButton* parts on the welcome window to the Object Factory parts 
representing the query windows, as follows: 

From part, feature To part, feature 

ContractGB, #buttonClickEvent ConQFac, #new 

ContractorGB, #buttonClickEvent CtrQFac, #new 

SkillGB, #buttonClickEvent SklQFac, #new 

Next, connect promoted button actions in the query windows to the Object Factory 
parts representing the information windows, as follows: 

From part, feature To part, feature 

ContractQ, #okPBButtonClickEvent ConVFac, #new 

ContractorQ, #okPBButtonClickEvent CtrVFac, #new 

SkillQ, #okPBButtonClickEvent SklVFac, #new 

Connecting the Object Factory Parts to Their Corresponding Variable Parts 

Once you have set both Object Factory and variable parts, you must connect them. 

In OAMain, the connections vary depending on whether the window is modal. Modal 
windows retain focus until they are closed; the user cannot switch focus to another 
window without closing the modal window. In OAMain, OAGenlnfo and the query 
windows are modal; the other windows are modeless. 
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Connections for modal windows 


Make the following connections for the query window parts. The connections for 
OAGenlnfo* are listed in “Completing the Menu Bar” on page 270. 


From part, feature 

ConQFac, #newEvent 
ConQFac, #newEvent 
ConQFac, #newEvent 
CtrQFac, #newEvent 
CtrQFac, #newEvent 
CtrQFac, #newEvent 
SklQFac, #newEvent 
SklQFac, #newEvent 
SklQFac, #newEvent 


To part, feature 

ContractQ, #this 
ContractQ, #setFocus 
ContractQ, #showModally 
ContractorQ, #this 
ContractorQ, #setFocus 
ContractorQ, #sho\vModally 
SkillQ, #this 
SkillQ. #setFocus 
SkillQ. #showModally 


Connections for modeless windows 


Now make the following connections for the modeless information windows: 


From part, feature 

ConVFac, #newEvent 
ConVFac, #newEvent 
ConVFac, #newEvent 
CtrVFac, #newEvent 
CtrVFac, #newEvent 
CtrVFac, #newEvent 
SklVFac, #newEvent 
SklVFac, #newEvent 
SklVFac, #newEvent 


To part, feature 

ContractV, #this 
ContractV, #setFocus 
ContractV, #visible 
ContractorV, #tliis 
ContractorV, #setFocus 
ContractorV, #visible 
SkillV, #this 
SkillV. #setFocus 
SkillV, #visible 


Making the Final Connections 

With all parts represented in the primary part, you have only to make the final 
connections. This includes the following: 

• Connecting the nonvisual parts to their corresponding variable parts 

• Completing the menu bar 
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Connecting the Nonvisual Parts to the Variables that Represent Them 

Each visual part contains promoted variables as placeholders for the static nonvisual 
parts dropped in OAMain. Now, connect the static parts to the variables that 
represent them as follows: 

From part, feature 

Contract, #this 
Contract, #this 
Contract, #this 
Contractor, #this 
Contractor, #this 
Skill, #this 
Skill, #this 
SkillBase, #this 
SkillBase, #this 
SkillBase, #this 
SkillBase, #this 

Completing the Menu Bar 

Now that all parts appear on the free-form surface, you can complete the menu bar. 
The connections echo those made in “Connecting to the Object Factory Parts” on 
page 268. 

Connections from the View submenu 

From part, feature 

ContractMI, #commandEvent 
ContractorMI, #commandEvent 
SkillMI, #commandEvent 
GenlnfoMI, #commandEvent 
GenlnfoMI, #commandEvent 

Connections from the Edit submenu 

From part, feature To part, feature 

ContractMI, #commandEvent ConVFac, #new 

ContractorMI #commandEvent CtrVFac, #new 

Once all connections are complete, you are ready to generate code. Make sure to 
save your work. 


To part, feature 

ConQFac, #new 
CtrQFac, #new 
SklQFac, #new 
VBDevelopment, #setFocus 
VBDevelopment, #showModally 


To part, feature 

ConQFac, #contract 
ConVFac, #contract 
CtrVFac, #contract 
CtrQFac, Contractor 
CtrVFac, Contractor 
SklQFac, #skill 
SklVFac*, #skill 
SklQFac, CkillBase 
SklVFac, CkillBase 
CtrQFac, #skillBase 
CtrVFac, CkillBase 
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Generating Source Code 
for Parts and Applications 


All work that you do using Visual Builder is stored within the Visual Builder 
development environment, including information about visual parts, nonvisual parts, 
and connections. 

This chapter describes all you need to know about getting your Visual Builder 
application ready for others to use. The topics covered are as follows: 

• Preparing for source code generation 

• Generating C++ source code for the individual parts used within your application 

• Generating C++ source code for your application (the main() function) 

• Preparing generated files for compilation 

• Compiling and linking your application 


Preparing for Source Code Generation 

Before getting started, decide how you want to build your application’s make file. 
You can create make files in either of the following ways: 

• From Visual Builder 

• Using WorkFrame’s makemake program 

Both options require the following advance preparation. 

Setting Up Visual Builder to Generate Make Files 

If you want Visual Builder to generate make files with the C++ source code, follow 
these steps from the Visual Builder window: 

1. From the menu bar, select Options. 

2. Select Preferences; then select Generate make files. 

The next step is described in “Generating C++ Source Code for Individual Parts” on 
page 272. 
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Setting Up Visual Builder Projects to Use WorkFrame’s makemake Program 

If you prefer to build your application’s make file using WorkFrame, make sure your 
Visual Builder project has the correct compile and link options set. Follow these 
steps from the desktop: 

1. Open the Settings notebook for your Visual Builder project. 

2. Select the Target notebook tab. Type an appropriate name in the Make file 
name field. 

3. Select the Actions notebook tab. 

4. Select the link action; then select the Options push button. 

5. Select the Templates notebook tab. 

6. Select the Templates used radio button; then select the compile action to 
associate with the link action. 

7. Select the OK push button. 

8. Select the File Names notebook tab. 

9. Under Libraries to use, type in: 
cppoov3i.1ib os2386.1ib 

10. Under Definition (.DEF) file name, type the appropriate module definition file 
name. 

11. Select the OK push button. 

12. Close the Settings notebook. 

The next step is “Generating C++ Source Code for Individual Parts.” 


Generating C++ Source Code for Individual Parts 

After you finish constructing a part, you must generate source code. If the part is an 
application in itself or if you want to test a part individually, you must also generate 
the code as described in “Generating Source Code for Your Application’s main() 
Function” on page 274. 

You can generate source code for the part being edited from any of the Visual 
Builder editors. 

1. From the editor’s menu bar, select File. 

2. Select Save and generate; then select Part source. 
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In addition, if you are using the Composition Editor, you can select , the 

icon for the Generate Part Code tool, on the tool bar. There is no difference between 
selecting this icon and using the menu item described previously. 


e 


One of the most common causes of code generation errors is changing the 
names of features that are connected to other features. For example, 
suppose feature A is connected to feature B. If you change the name of 
feature A and then regenerate the source code for your part. Visual Builder 
displays an error. This can also occur if you change the name of a 
promoted feature. To correct the error, double-click on the connection 
arrow and replace the incorrect feature name with the correct one. 


For more information about the files generated, see “Source Files Created during Part 
Code Generation.” 


The next step is described in “Generating Source Code for Your Application’s main!) 
Function” on page 274. 


Source Files Created during Part Code Generation 

For each part processed. Visual Builder generates several source code files. As an 
example, the following files are created for the OAContractView part: 


contractg.cpp 

contractg.hpp 

contractg.h 

contractg.rc 


A C++ code file. 

The header file for contractg.cpp. 

A resource header file for the .cpp file. This file contains the 
resource IDs for your part. 

A resource file that contains any text strings used in the part for 
entry field labels, push buttons, menus, and so forth. 


If you selected Default to FAT file names under the Options pull-down menu of the 
Visual Builder window and your part name has more than eight characters. Visual 
Builder creates an eight-character name for the part when it is created. 

Note: If you are using the File Allocation Table (FAT) file system, we recommend 
that you always use part names and file names that have eight characters or 
less, even if you have selected the Default to FAT file names option. 
Otherwise, Visual Builder might use a file name for a .vbb file that is the 
same as one that already exists and write over the existing file. 


For information about how the .h and .rc files are used for translation, see 
Chapter 19, “Enabling National Fanguage Support for an Application” on page 293. 
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Generating Source Code for Your Application’s mainQ Function 

To create an executable application, you must generate code for the standard C++ 
main() function. You can do this for parts that you want to test individually or for 
your entire application. If you want to compile your entire application, generate the 
function using the part that represents your application’s primary view. 

You must first generate the C++ code for all parts that you intend to compile in your 
application. Load into Visual Builder the .vbb files that represent all parts that will 
appear in the compiled application. Then, generate the main() function from the part 
that you want to appear first when your application is started (the main part). 

You can generate application source code for the main() function if the main part is 
displayed in any of the Visual Builder editors. 

1. From the editor’s menu bar, select File. 

2. Select Save and generate; then select main() for part. 

For more information about the files generated, see “Source Files Created during 
Generation of main() Function Code.” 

Source Files Created during Generation of main() Function Code 

For each main part processed. Visual Builder creates several files. For the OAMain 
part, the following files are created: 

oamain.app The C++ code file containing the main() function declaration. 

Note: If you start Visual Builder from a WorkFrame project, a file 
named vbmain.cpp is generated instead of a file named 
oamain.app. 

oamain.mak A make file, if you opted to generate make files using Visual 
Builder. 

If you selected Default to FAT file names as a preference under the Options 
pull-down menu of the Visual Builder window and your part name has more than 
eight characters. Visual Builder creates an eight-character name for the generated 
files. 

Note: If you are using the File Allocation Table (FAT) file system, we recommend 
that you always use part names and file names that have eight characters or 
less, even if you have selected the Default to FAT file names option. 
Otherwise, Visual Builder might use a file name for a .vbb file that is the 
same as one that already exists and write over the existing file. 
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Preparing Generated Files for Compilation 

Before compiling your application, be sure you have the following files: 

• Header files for all parts 

• .cpp files for all parts 

• A make file 

• An .app file for the main part 

Note: If you start Visual Builder from a WorkFrame project, you should have a 
file named vbmain.cpp instead of an .app file. 

Final preparations for compilation and linking include the following: 

• Specifying additional libraries (C++ libraries and DLLs) in the make file 

• Specifying debug options for the compiler and linker programs 

Specifying Additional Libraries in the Make File 

Review the list of libraries specified in the make file, particularly libraries for parts 
that you compiled separately. 

If your application uses DLLs, add the DLL names as dependent files in the 
description blocks used to keep the object files up to date. The order in which you 
list object files is significant. Files with external references must occur after the 
referred-to files. 

Specifying the Option to Generate Browser Information 

If your want the VisualAge C++ compiler to generate Browser information, you must 
include the -Fb+ option when you compile your application. This option causes the 
compiler to generate a file with an extension of .pdb. Once this file is generated, you 
can use the Browser data when connecting features to member functions and for other 
purposes. For more information, see “Using Browser Information” on page 187. 

Specifying Debug Options for the Compiler and Linker Programs 

If you prefer to compile and link your application using WorkFrame, you should have 
already specified debug options in your Visual Builder project file. For more 
information about the options you need to set, see the WorkFrame documentation. 

If you opted to let Visual Builder generate your make file. Visual Builder adds debug 
options to the make file by default. If you do not want your application compiled 
with debugging turned on, remove the /Ti + option. 

For more information, refer to the VisualAge C++ Language Reference. 
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To make Visual Builder connections easier to debug, set up a trace by following these 
steps: 

1. In your config.sys file, add this line: 

SET ICLUI TRACETOSTDOUT 

2. In your make file, add this phrase at the end of the GCPPFLAGS statement, but 
before the back slash (\): 

-DIC_TRACE_DEVELOP 

3. When you run your compiled application, redirect the output to a file. For 
example, run myapp.exe as follows: 

myapp > myapp.out 

Browse the output file (myapp.out) to see what connections were fired and in 
what order. 


Compiling and Linking Your Application 

You can compile your application from the OS/2 command line or from WorkFrame. 

To call both the compiler and linker programs, you can run the Toolkit’s nmake 

program. Regardless of how you choose to compile and link your Visual Builder 

application, use the following compile and link options: 

B"/DE /pmtype:pm" Passes the string /DE /pmtype:pm to the linker as parameters. 

C Compiles and links. 

Fb+ Generates Browser information in a file with a .pdb 

extension. 

Ft (dir) Generates files for template resolution and puts them in the 

dir directory. 

Gd+ Dynamically links to the runtime library. 

Gm+ Builds an .exe file. 

I Searches the directory of the source file for include files; 

then, searches paths specified in config.sys include variable. 

Q Displays the compiler logo when invoking the compiler. 

Ti+ Generates debugger information. This is optional but 

recommended. 

Tdp Compiles all source files as C++ files and ensures that 

template functions are resolved. 
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For more information on compiling and linking, refer to the VisualAge C++ 
Programming Guide. 
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Part 4. Extending Visual Builder Applications 

This part provides the information you need to extend your applications beyond the 
basic functions that Visual Builder provides. 
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This chapter describes how you can use your existing C and C++ code in applications 
that you create with Visual Builder. 


Defining the Part Interface Using Part Information Files 

If C++ code already exists for your Visual Builder application, you can more 
efficiently define the part interface using part information files. This involves the 
following steps: 

1. Determine the part’s features. 

2. Create a part information file using your favorite editor. This file can include 
information for as many parts as you need. 

3. In Visual Builder, import the part. 


Creating a Part Information File 

To create a part information file, add information about your part's part interface to a 
file using your preferred editor. The following example shows how you could specify 
part information for the OAContractor part: 


//VBBeginPartlnfo: OAContractor,"Contractor part for OASearch sample" 

//VBParent: IStandardNotifier 

//VBindudes: "Cntrctor.hpp" _0AC0NTRACT0R_,"iprofi1e.hpp","istring.hpp","iexcbase.hpp" 

//VBPartDataFi1e: OANONVIS.VBB 

//VBConstructor: OAContractorQ 

//VBComposerlnfo: nonvisual,802,cppov33r 

//VBEvent: ready, "ready", readyld 

//VBAction: getContractor, 

//VB: "Get contractor data from database", 

//VB: OAContractor&, 

//VB: OAContractor& getContractor() 

//VBAction: putContractor, 

//VB: "Add or update contractor data in database", 

//VB: OAContractor&, 

//VB: OAContractor& putContractor() 

//VBAction: parseName, 

//VB: "Parse user input to get contractor's name", 

//VB: OAContractor&, 

//VB OAContractor& parseName(const IString& aName) 

//VBAttribute: contractorlD, 

//VB: "Contractor's employee identifier", 

//VB: IString, 

//VB: IString contractorID() const,, 

//VB: contractorlDId 

//VBAttribute: lastName, 

//VB: "Contractor's last name", 

//VB: IString, 

//VB: IString lastNameQ const, 

//VB: OAContractor& setLastName(const IString& aLastName), 

//VB: lastNameld 
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//VBAttribute: 
//V B: 

//V B: 

//V B: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 

//VBAttribute: 

//VB: 

//VB: 

//VB: 

//VB: 

//VB: 


firstName, 

"Contractor's first name", 

IString, 

IString firstName() const, 

OAContractor& setFirstName(const IString& aFirstName), 
firstNameld 
middlelnitial, 

"Contractor's middle initial", 

IString, 

IString middlelnitial() const, 

OAContractor& setMiddlelnitial(const IString& aMiddlelnitial), 

middlelnitialId 

homeStreet, 

"Contractor's home street address", 

IString, 

IString homeStreet() const, 

OAContractor& setHomeStreet(const IString& aHomeStreet), 

homeStreetld 

homeCity, 

"Contractor's home city", 

IString, 

IString homeCity() const, 

OAContractor& setHomeCity(const IString& aHomeCity), 

homeCityld 

homeState, 

"Contractor's home state or province", 

IString, 

IString homeState() const, 

OAContractor& setHomeState(const IString& aHomeState), 

homeStateld 

homeZip, 

"Contractor's home postal code", 

IString, 

IString homeZipO const, 

OAContractor& setHomeZip(const IString& aHomeZip), 

homeZipId 

phoneNumber, 

"Contractor's daytime phone number", 

IString, 

IString phoneNumberQ const, 

OAContractor& setPhoneNumber(const IString& aPhoneNumber), 

phoneNumberld 

startDate, 

"Contractor's starting date with OA", 

IString, 

IString startDate() const, 

OAContractor& setStartDate(const IString& aStartDate), 

startDateld 

endDate, 

"Contractor's last day with OA (empty if active)", 

IString, 

IString endDate() const, 

OAContractor& setEndDate(const IString& aEndDate), 

endDateld 

activeStatus, 

"Whether contractor actively seeks contract work". 

Boolean, 

Boolean isActiveStatus() const, 

OAContractor& enableActiveStatus(Boolean enable = true), 

activeStatusId 

currentContract, 

"Contractor's current assignment, if any", 

IString, 

IString currentContract() const, 

OAContractor& setCurrentContract(const IString& aCurrentContract), 
currentContractld 
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//VBPreferredFeatures: enabledForNotification, getContractor, putContractor, this 
//VBEndPartlnfo: OAContractor 


Note the following syntax: 

• The VBBeginPartlnfo and VBEndPartlnfo statements delimit the part information 
for OAContractor. 

• The VBPart statement specifies the base class for OAContractor, 

IS tandardNotifier*. 

• The VBIncludes statement specifies a header file to be added in an #include 
directive when the code is generated. 

• The VBPartDataFile statement specifies the .vbb file that holds the information 
for OAContractor. 

• The VBComposerlnfo statement indicates that this is a nonvisual part. The 
absence of the abstract keyword indicates that this is a concrete part that can be 
dropped on the free-form surface. 

• The VBEvent, VBAction, and VBAttribute statements define features for this 
part. 

For information about part definition syntax, refer to Building VisualAge C++ Parts 
for Fun and Profit. 

Importing the Part 

Before importing the part, you must create a part information file. To import the 
part, follow these steps from the Visual Builder window: 

1. From the menu bar, select File. Select Import part information. 

The Enter Name for Part Information File window appears. 

2. Specify the path and name of the part information file that contains the 
information that you want to import. When the import is finished, the name of 
the part appears in in the Visual Builder window. 

If C++ code for your part already exists, your part is finished. If you want to change 
the part interface later, do either of the following: 

• Use the Part Interface Editor to edit feature specifications. You must use this 
method to delete features. 

• Edit your part information file and re-import the part information. 

If C++ code for your part does not exist, see “Adding Code to Your Part” on 
page 105. 
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Adding Categories and Parts to the Parts Palette 


The purpose of this chapter is to introduce you to the concepts and steps involved in 
adding categories and parts to and removing categories and parts from the parts 
palette. You can modify the parts palette at any time and from any of the Visual 
Builder editors or from the Visual Builder window. 

One reason to modify the parts palette is so that you can quickly and easily place 
parts that you have created and that you use often on the free-form surface. 

Otherwise, you have to place them by selecting Options—»Add part, which requires 
you to know the exact class name of the part that you are placing. 

Another reason to modify the parts palette is to give everyone who is working on the 
same project access to the same set of standardized parts. Your company could have 
a parts builder who builds these standardized parts and puts them in a category on the 
parts palette for you to use. 

Group parts that behave similarly in the same category. You can see by looking at 
the parts palette how we have grouped the parts that we provided into categories 
based on their behavior. For example, all parts that are used for data entry are in one 
category, all parts that contain and display lists are in another category, and so forth. 

This chapter contains an example that uses the OAContractor nonvisual part created 
in Chapter 7, “Creating Nonvisual Parts” on page 101, but you can use any part that 
you have created. When you finish the example, you have a new OAModels 
category and a new OAContractor part on the parts palette. 


Preparing Icons for the Parts Palette 


Each category and part on the Visual Builder parts palette is represented by an icon, 
so you can recognize it visually. With Visual Builder, you can create and use your 
own icons when you extend the parts palette. If you do not, you can still extend the 


parts palette and accept the default category icon, 


icon. 



, and the default part 
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This example uses 


tit 


for the OAModels category and 



for the 


OAContractor part, which are stored in the cppov33r.dll file as resource numbers 
800 and 802, respectively. 


To prepare icons for use with Visual Builder, do the following: 

1. Create your icons. One way to do this is to use your operating system toolkit 
icon editor. 

For VGA displays on OS/2, use the Independent VGA form (32x32). For higher 
display resolutions on OS/2, use the 8514-16 colors form (40x40). 

2. Create a resource DLL that contains your icons. Use files similar to the 
following: 

• userpal.c 

empty() 

{ 

} 

• userpal.rc 

icon 800 oamodels.ico 
icon 801 oacontractor.ico 

• userpal.def 

1ibrary userpal 

description 'Icons for user-extended palette 1 

• userpal.mak 

userpal.dll: userpal.obj userpal.def userpal.res 
icc userpal.obj /Feuserpal.dl1 userpal.def 
rc userpal.res userpal.dll 

userpal.obj: userpal.c 
icc /C+ userpal.c 

userpal.res: userpal.rc 
rc -r userpal.rc 


Once you have the files ready, type the following to build the resource DLL: 
nmake userpal.mak 

3. Place the resource DLL in a directory in your LIBPATH. 

Your icons are now ready for use with Visual Builder. 
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Adding a Category to the Parts Palette 

Now that you have your icons prepared in a resource DLL, you are ready to extend 
the parts palette. To add a category to the parts palette, do the following: 

1. In the Composition Editor, select Modify Palette-*Add New Category from the 
Options pull-down menu. 

The Add palette category window is displayed as follows: 



-Graphic- 

□ 

Module name dde4vr30 
ID 150 

.-Shading- 

Q Light ® Normal Q Dark 

i-Type of Graphic- 

®lcon O Bitmap JNone 


OK 


Cancel 



Figure 114. The Add Palette Category Window 


Notice that the default category icon. 


, is specified. It is stored as 


resource ID 150 in the dde4vr30.dll resource file provided with Visual Builder. 


2. Type OAModel s or the name that you want for your category in the Category 
name field. 


3. Type cppov33r or the name of your resource DLL in the Module name field. 
Note: Do not type the .dll file extension in the Module name field. 

4. Type 800 or the resource ID of the icon in your resource DLL in the ID field. 

Note: After you enter the resource ID number, move the cursor to another 

component in the window, such as the Module name field, if you want 
to see the graphic that will be used before continuing. 
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5. Select the OK push button. 

Your category with the icon specified is added to the parts palette. 

How new category or part information is saved 

When you create a new category or part. Visual Builder stores information about that 
category or part in a file named vbpalet.dat, which is stored in your current directory. 
This file is written automatically, so you do not need to save anything. 

The vbpalet.dat file is read each time you start Visual Builder. The information this 
file contains causes any categories or parts that you have added to be included on the 
parts palette. 

Removing a category or part that you just added 

The vbpalet.dat file also allows you to undo and redo any changes you make to the 
parts palette. For example, after adding a category or part during the current edit 
session, you can select Edit^Undo to remove the part or category you just added. 
Selecting Edit—»Redo would put the part or category back on the parts palette, again. 

Once you close the Composition Editor, you can no longer undo or redo any changes. 


Specifying a Unique Icon for a Part You Add to the Parts Palette 

You can specify a unique icon for a part that you add to the parts palette, but you 
must do so before you add it to the parts palette. To give your part a unique icon, do 
the following: 

1. Open the part. 

2. Switch to the Class Editor. 

3. Enter the name of the DLL file that contains the icon you want to use in the 
DLL Name field. 

4. Enter the resource ID number for the icon in the Resource Id field. 

If you enter a valid DLL file name and resource ID number. Visual Builder 
displays the icon below the Resource Id field. This allows you to verify the 
icon before adding it to the parts palette. 

5. Select File^Save to save the resource DLL and resource ID information in the 
Class Editor. 
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Adding a Part to the Parts Palette 

You can add a part to any category on the parts palette using any of the following 
methods: 

• Adding a part that is selected in the Visual Builder window 

• Adding the part that you are currently editing 

• Adding any part whose .vbb file is loaded 

Adding a Part That Is Selected in the Visual Builder Window 

To add a part to the parts palette from the Visual Builder window, do the following: 

1. Load the .vbb file that contains the part you want to add to the parts palette if it 
is not already loaded. 

2. Select the .vbb file. For this example, select oanonvis.vbb. 

3. Select the part you want to add. For this example, select OAContractor. 

Note: You can add multiple parts by holding down the Ctrl key and clicking on 
each part that you want to add. 

4. Select Part-* Add to palette. 

Visual Builder displays the Add to Palette window, as shown in the following 
figure: 


Add to Palette 


Parts 


OAContractor 


□ 


Category 

Buttons 
Data entry 
Lists 

Frame Extensions 

Sliders 

Composers 

Models 

Other 

OAModels 


1_1 



Add 


Cancel 

Help 


Figure 115. Add to Palette Window 

5. Select the part that you want to add. For this example, select OAContractor. 

6. Select the category that you want to add the part to. For this example, select 

OAModels. 

7. Select the Add push button. 
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Visual Builder adds the OAContractor part to the parts palette in the OAModels 
category. 


Adding the Part That You are Currently Editing 

You can add the part that you are currently editing to the parts palette from either the 
Composition Editor, the Class Editor, or the Part Interface Editor. To add the part 
that you are currently editing to the parts palette, do the following: 

1. Double-click on the OAContractor part in the Visual Builder window. 

Visual Builder opens the OAContractor part in the Part Interface Editor. 

2. Select File^Add to palette. 

Visual Builder displays the Add to Palette window, as shown in the following 
figure: 


pwiEia-HHia 


□ 


Part class OAContractor* 

Category 


Buttons 


Data entry 
Lists 

Frame Extensions 

Sliders 

Composers 

Models 

Other 

OAModels 


Add Cancel | Help | 


Figure 116. The Add to Palette Window 

The Part name field shows the name of the part that you are editing. This is the 
part that is to be added to the parts palette. You cannot change the name of the 
part displayed in this field. In this example, OAContractor is displayed in this 
field. 

3. Select the category that you want to add the part to. For this example, select 
OAModels. 

4. Select the Add push button. 

The OAContractor part is added to the OAModels category on the parts palette. 
To see this, switch to the Composition Editor and select the OAModels category. 
The icon for the OAContractor part is displayed in the parts column. 
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Adding Any Part Whose .vbb File Is Loaded 

You can add any part to the parts palette as long as its .vbb file is loaded in the 
Visual Builder window. The following steps explain how to do this: 

1. In the Composition Editor, select Modify Palette^-Add New Part from the 
Options pull-down menu. The Add to Palette window is displayed as follows: 



Part class 


Category 




Data entry 

Lists 

Frame Extensions 
Sliders 

Composers 

Models 

Other 

OAModels 



Add Cancel : Help 


Figure 117. The Add to Palette window 

To add a part to the parts palette, do the following: 

a. Type OAContractor in the Part name field or the class name of the part you 
want to add. 

b. Select OAModel s in the Category list or the name of the category to which 
you want to add your part. 

c. Select the Add push button. 

Your part is added to the parts palette in the specified category. 

Notice that the part you just added uses the same icon as the part it inherits from. If 
you inherit from a part whose icon does not appear on the parts palette, such as 
IStandardNotifier*, or for which you have not provided a resource DLL, Visual 

Builder uses the default part icon, 
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Deleting a Category or Part from the Parts Palette 

To delete a part from the parts palette, do the following: 

1. Select the part on the parts palette. 

2. Select Modify Palette-^Delete Part from the Options pull-down menu. 

The selected part is deleted from the parts palette. 

To delete a category from the parts palette, do the following: 

1. Select the category on the parts palette. 

2. Select Modify Palette -^Delete Category from the Options pull-down menu. 
The selected category and all of the parts in it are deleted from the parts palette. 


Saving Parts Palette Changes 

Visual Builder automatically saves all parts palette changes for you. When you create 
a new category or part. Visual Builder stores information about that category or part 
in a file named vbpalet.dat, which is stored in your current directory. This file is 
written automatically. 

Once you add or delete categories or parts, the vbpalet.dat file is read each time you 
start Visual Builder. The information this file contains causes any categories or parts 
that you have added to be included on the parts palette. It also prevents any 
categories or parts that you have deleted from appearing on the parts palette. 

If you update the icon associated with a part, the parts palette is updated the next 
time you select the category in which the icon appears. 

Removing a category or part that you just added 

The vbpalet.dat file also allows you to undo and redo any changes you make to the 
parts palette, but only during the current Composition Editor session. For example, 
after adding a category or part, you can select Edit—»Undo to remove the part or 
category you just added. Selecting Edit^Redo would put the part or category back 
on the parts palette, again. 

Once you close the Composition Editor, you can no longer undo or redo any changes. 
However, you can still add categories and add parts, as well as delete categories and 
parts. 
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Enabling National Language Support 
for an Application 


Because many languages exist in the world today, consider designing your 
applications to be language friendly, that is, user-friendly for all languages. There are 
several different aspects to consider when creating an application that is language 
friendly: 

• First, there is the text that the user sees. This text includes labels in your 
windows and messages that are displayed. 

• Next, there is specific country information. This includes date separators and 
time formats. 

• Finally, some languages include characters that require two bytes to represent 
those characters and are primarily found in the Asian languages, such as 
Japanese. 


e 


A good rule to follow: Do not place any translatable text or country 
symbols directly into your source code. Place them in an external file 
where they are easily accessible for translation. 


Visual Builder provides for ease of national language support in the following ways: 

• Using resource files for translation 

• Using canvases to adjust the size for translated text 

• Specifying data types with country-sensitive formatting 

• Providing double-byte character set (DBCS) support for Asian languages 

For additional information about national language and DBCS support, refer to the 
IBM Open Class Library User’s Guide. 


Using Resource Files for Translation 

In Chapter 16, “Generating Source Code for Parts and Applications” on page 271, 
you learned that Visual Builder generates the following resource files for you: 

• A resource file (partname. rc), which contains the text strings used in your part 

• A resource header file (partname. h), which contains the resource IDs for your 
application 
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The resource (partname.rc) file 

The .rc file groups resources into two categories:window resources and nonwindow 
resources. The window resources are the text strings that are associated with window 
IDs for information area text and fly-over text. 

The nonwindow resources are the text strings that are displayed in your composite 
part. Examples are window titles, static text used to label entry fields and list boxes, 
and the text on push buttons and menu items. These text strings are delimited by 
quotation marks (") and can be translated into another language. 


Here is the todolist.rc file that we generated for the To-Do List application shown in 
Chapter 2, “Creating a Simple Visual Builder Application” on page 7: 

I / ■k-k'kick-k-k-k-k-kick-k-kick-k-k'k-k-k-kick-k-kick-k-k'k-k-k-kick-k-kick'k-k-k'k-k-kick-k-k-k-k-k-k-k-k-k-kick-k 

// Resource file for: ToDoList.cpp 

If-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k 

linclude "ToDoList.h" 

linclude <os2.h> 

#ifndef MAIN_RESOURCES_INCLUDED 
fdefine MAIN_RESOURCES_INCLUDED 

HELPTABLE WND_ToDoList 
BEGIN 

HELPITEM WND_ToDoList_FrameWindow, WND_ToDoList_FrameWindow, 0 
END 

fdefine ToDoList_WINDOWRESOURCES 
Idefine ToDoList_NONWINDOWRESOURCES 
STRINGTABLE 
BEGIN 

1, "Visual Builder 3.0" 

END 


#endif 


#ifdef ToDoListJIONWINDOWRESOURCES 
#ifndef ToDoList_NONWINDOWRESOURCES_INCLUDED 
Idefine ToDoList_NONWINDOWRESOURCES_INCLUDED 
STRINGTABLE 
BEGIN 


STRRC_ToDoList_FrameWindow_titie, 
STRRC_ToDoList_StaticTextl_text, 
STRRC_ToDoList_EntryFieldl_text, 
STRRC_ToDoList_StaticText2_text, 
STRRC_ToDoList_PushButtonl_text, 
STRRC_ToDoList_PushButton2_text, 


"To-Do List" 
"To-do item" 

II II 

"To-do list" 
"Add" 

"Remove" 
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#endif 
#endif 

lifdef ToDoList_WINDOWRESOURCES 
HELPSUBTABLE (WND_ToDoList_FrameWindow) 

BEGIN 

END 

#endif 

#ifdef ToDoList_HELPITEMRESOURCES 

HELPITEM WND_ToDoList_FrameWindow, WND_ToDoList_FrameWindow, 0 

#endif 

#ifdef ToDoList_HELPSUBITEMRESOURCES 
#endif 


The window resources and nonwindow resources are grouped into separate string 
tables so that translators can easily find the text that is to be translated. 

You may have text strings in your part, such as the application name, that you do not 
want translated. If that is the case, you can prevent those text strings from being 
inserted in the .rc file by inserting a number sign (#) at the beginning of the text and 
enclosing the text in quotation marks ("). This change must be made in the settings 
notebook for the part, not in the Composition Editor. 

For example, suppose you do not want the text in the window title, To-Do List, to be 
translated. To prevent Visual Builder from inserting this text string in the .rc file, 
you would open the settings notebook for the ToDoList part, find the entry field on 
the General page that contains the title text, and change it to the following: 

#"To-Do List" 

Notice that each text string that Visual Builder inserts in the .rc file is preceded by a 
#define statement that begins with STRRC. These #define statements represent the 
resource ID of each text string. Visual Builder generates these #define statements and 
defines them in the partname .h file. By inserting and defining these #define 
statements. Visual Builder relieves you from the task of having to specify resource 
IDs for each text string. 

To help Visual Builder generate these #defme statements properly, you must enter the 
starting resource ID for your part. The following section explains how to do this. 
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The resource header (partname.h) file 

The .h file contains a list of #define statements. Visual Builder uses these #define 
statements in the .re file to assign unique resource IDs to each of the text strings that 
you use to create your composite part and a unique window ID to all primitive visual 
parts. The only resource ID that you need to specify is the starting resource ID for 
the part. 

Here is the todolist.h file that we generated for the To-Do List application shown in 
Chapter 2, “Creating a Simple Visual Builder Application” on page 7: 

/ /■k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k1ck-k‘k-k-k‘k-k-k‘k'k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k-k , k-k 

// Resource header file for: ToDoList.cpp 
! /************************************************************* 

#ifndef _ICC0NST_ 

#include <icconst.h> 

#endif 

#ifndef _IVBDEFS_ 

#include <ivbdefs.h> 

#endif 

#ifndef RC_ToDoList 
#define RC_ToDoList 10000 
#endif 

#ifndef WND_ToDoList 

#define WND_ToDol_ist VBBASEWINDOWID 

#endif 

#define WNDOFFSET_ToDoList_FrameWindow 0 

#define WND_ToDoList_FrameWindow WND_ToDoList 

#define STRRC_ToDoList_FrameWindow_title RC_ToDoList+0 

#define WNDOFFSET_ToDoList_Canvas 1 

#define WND_ToDoList_Canvas WND_ToDoList + WNDOFFSET_ToDoList_Canvas 
#define WNDOFFSET_ToDoList_StaticTextl 2 

#define WND_ToDoList_StaticTextl WND_ToDoList + WNDOFFSET_ToDoList_StaticTextl 
#define STRRC_ToDoList_StaticTextl_text RC_ToDoList+1 

#define WNDOFFSET_ToDoList_EntryFieldl 3 

#define WND_ToDoList_EntryFieldl WND_ToDoList + WNDOFFSET_ToDoList_EntryFieldl 
#define STRRC_ToDoList_EntryFieldl_text RC_ToDoList+2 

#define WNDOFFSET_ToDoList_StaticText2 4 

#define WND_ToDoList_StaticText2 WND_ToDoList + WNDOFFSET_ToDoList_StaticText2 
#define STRRC_ToDoList_StaticText2_text RC_ToDoList+3 

#define WNDOFFSET_ToDoList_PushButtonl 5 

#define WND_ToDoList_PushButtonl WND_ToDoList + WNDOFFSET_ToDoList_PushButtonl 
#define STRRC_ToDoList_PushButtonl_text RC_ToDoList+4 

#define WNDOFFSET_ToDoList_PushButton2 6 

#define WND_ToDoList_PushButton2 WND_ToDoList + WNDOFFSET_ToDoList_PushButton2 
#define STRRC_ToDoList_PushButton2_text RC_ToDoList+5 
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Idefine WNDOFFSET_ToDoList_ListBoxl 7 

Idefine WND_ToDoList_ListBoxl WND_ToDoList + WNDOFFSET_ToDoList_ListBoxl 


Find the first #define statement in the todolist.h file. It is the RC_ToDoList #define 
statement. The number to the right of this #define statement, 10000, is the starting 
resource ID. This is the default number that Visual Builder inserts when you select 
the check box next to the Starting resource id field in the Class Editor. Visual 
Builder uses this number as the resource ID of the first text string and increments the 
resource ID of each successive text string by 1. 

We chose to use the default number 10000 for the following reasons: 

• The resource ID must be a number. 

• The number specified must be either high enough or low enough that it does not 
conflict with the resource IDs that Visual Builder generates for the primitive parts 
(entry field, push buttons, and so forth) that are used to compose the ToDoList 
part. 

When determining resource IDs for window resources. Visual Builder begins with 
15000 and increments the resource ID of each successive primitive part by 5. 
Therefore, we recommend using starting resource IDs between 100 and 14500 for 
most applications for the following reasons: 

• You should not use resource IDs below 100 because Presentation Manager has 
reserved many of them for its own use. 

• Numbers between 100 and 14500 are low enough to prevent you from 
experiencing any resource ID conflicts in most cases. 

Specifying the starting resource ID for subparts 

If you use a part that you have created as a subpart, specify a starting resource ID for 
both the subpart and the part in which the subpart is embedded. Do this to prevent 
conflicts between the resource IDs that Visual Builder generates for your subpart and 
those it generates for the part in which the subpart is embedded, as described in the 
preceding section. Otherwise, Visual Builder uses the same starting resource IDs for 
both the subpart and the part in which it is embedded, which causes compile errors. 

For example, suppose you have a reusable Address part (a canvas with entry fields 
and static text) that you want to embed as a subpart in the frame window of your 
application’s main view. You might give the main view a starting resource ID of 
5000 and the Address part a starting resource ID of 6000. Doing this would prevent 
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conflicts with the resource IDs that Visual Builder generates for the main view and 
those it generates for the Address part. 


Using Canvases to Adjust Size for Translated Text 

When text is translated from one language to another, the translated text often 
occupies more space than the original text occupied. This can cause problems 
because the layout of the user interface can be disrupted by the longer text strings. 

Two of the canvas parts that Visual Builder provides solve this problem for you: 
ISetCanvas* and IMultiCellCanvas*. These parts allow you to insert translated text 
and rebuild your application without having to change the position of any of the parts 
in the user interface. The ISetCanvas* and IMultiCellCanvas* parts automatically 
adjust their size at run time to allow for longer text strings, taking into account the 
current window’s text size and font. 

For example, suppose you are using an ISetCanvas* part with three vertical decks and 
three rows of IRadioButton* parts in each deck. Once the text strings for the 
IRadioButton* parts are translated, all you have to do is rebuild your application. 

The decks in the ISetCanvas* part automatically adjust their widths to allow for the 
size of the translated text strings. 

The IMultiCellCanvas part is also good for translation purposes because the rows and 
columns automatically adjust themselves to fit the translated text. 


Specifying Parts with Country-Sensitive Formatting 

Visual Builder provides the following class interface parts that allow you to specify 

how information is presented for specific national languages: 

IDate This part allows you to customize the date formatting for the selected 

part. This includes specifying the order for the month, day, and year, 
and the character to use as a separator. 

ITime This part allows you to customize the time formatting for the selected 

part. This includes specifying the 12- or 24-hour format and the 
character to use as a separator. 
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Providing Double-Byte Character Support for Asian Languages 

The following Visual Builder parts provide DBCS support: 

IBuffer 

Class interface part that defines the contents of an IString. This part provides 
attributes to determine whether part or all of the characters in a buffer are DBCS or 
multi-byte character set (MBCS) characters, and whether they are valid DBCS or 
MBCS characters. 

IDBCSBuffer 

Class interface part that implements the version of IString contents that supports 
mixed OS/2 DBCS characters. This part ensures that MBCS characters are 
processed properly. 

IEntryField 

Visual part that creates and manages an entry field control. On the General page 
of the settings notebook for this part, you can specify the type of data that the user 
can enter. It can be one of the following: 

SBCS Sets the entry field to accept SBCS text only. 

DBCS Sets the entry field to accept DBCS text only. 

Mixed Sets the entry field to accept text that is a mixture of SBCS and DBCS 

characters. Conversion from an ASCII DBCS code page to an 
EBCDIC DBCS code page can result in a possible increase in the 
length of the data because of the addition of shift-in and shift-out 
characters, but it does not exceed the text limit of the entry field. 

Any Sets the entry field to accept text that is a mixture of SBCS and DBCS 

characters. This setting is the opposite of mixed. If the text contains 
both SBCS and DBCS characters and is to be converted from an 
ASCII code page into an EBCDIC code page, this style causes an entry 
field to not account for shift-in and shift-out characters that would be 
introduced into its text. 

IF rame Window 

Visual part that creates and manages a frame window control. This part has a style 
option, appDBCSStatus, that includes a DBCS status area in the frame window 
when it is displayed in a DBCS environment. IFrameWindow also has a member 
function, shareParentDBCS Status, that causes a child frame window to share the 
DBCS status area of its parent. 

IKeyboardEvent 

Class interface part that represents a keyboard-related event. An IKeyboardEvent 
object is created by a keyboard handler when a user presses or releases a key. The 
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part provides a virtualKey attribute that returns the virtual key code of the key. 
Two of the codes it can return are firstDBCS and lastDBCS. 

IString 

Class interface part that is an array of characters. This part provides attributes to 
determine whether part or all of the characters in a string are DBCS or MBCS 
characters, and whether they are valid DBCS or MBCS characters. 
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Using Direct-to-SOM Objects 
In Visual Builder Applications 


This chapter shows you how to use a Direct-to-SOM object in a Visual Builder 
application. SOM is the IBM System Object Model, which defines an interface 
between programs, or between libraries and programs, so that an object’s interface is 
separated from its implementation. SOM allows classes of objects to be defined in 
one programming language and used in another, and it allows libraries of such classes 
to be updated without requiring client code to be recompiled. 

You can make classes and member functions in existing C++ programs 
SOM-accessible without having to rewrite class and member function definitions. 

You do this by adding SOM C++ compiler directives to your code. Although SOM 
imposes some restrictions on C++ coding conventions, you should be able to convert 
most C++ programs for SOM support with minimal effort. 

VisualAge C++ can convert existing C++ classes to SOM classes. The 
VisualAge C++ compiler translates C++ code into Interface Definition Language 
(IDL) code, which you then compile with the SOM compiler to create your SOM 
objects. This method of creating SOM objects is referred to as the C++ 
Direct-to-SOM, or DTS, method. Currently, the only SOM objects that Visual 
Builder supports are DTS objects. 

To use a DTS object in an Visual Builder application you must do the following: 

1. Create the DTS object or objects. 

You will need the .hh and .lib files that you created in this step when compiling 
your Visual Builder application. You need the .dll when you run your compiled 
Visual Builder application. 

The DTS objects that you create must have the following characteristics: 

• DTS objects can have actions only; no attributes or events are allowed. DTS 
objects are not able to notify other parts when events occur. Therefore, no 
events or attribute event identifiers can be used. 

• You can implement actions using C++ and classes in the IBM Open Class 
Library. However, the actions can return only basic C data types and their 
parameters must be basic C data types. For example, instead of returning an 
IString data type, an action could return a char*. 

To learn how Visual Builder can help you avoid the DTS restrictions stated in 
the preceding list, see “Bypassing DTS Limitations” on page 305. 
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2. Create and import a part information file (.vbe file) for your DTS objects. 

3. Create a Visual Builder application using DTS objects. 

4. Generate and compile the code. 

5. Run your application. 

Make sure you have the .dll for the DTS object for this step. 

The sections that follow assume that you have already created your DTS object or 
objects, so they only discuss creating and importing the part information file, and 
creating a Visual Builder application using DTS objects. 

For information on creating DTS objects, refer to the VisualAge C++ User’s Guide. 
For information on generating and compiling your Visual Builder application code, 
see Chapter 16, “Generating Source Code for Parts and Applications” on page 271. 

We begin with creating and importing the part information file. 


Creating and Importing the Part Information File 

In “Defining the Part Interface Using Part Information Files” on page 281, you 
learned how to create a part information file. Create a file like this for your DTS 
objects. There are only two requirements when creating this file: 

• As we explained in the preceding section, DTS objects can only have actions. 
This makes DTS objects the equivalent of class interface parts because they have 
no notification capability. Therefore, you must set the VBComposerlnfo 
statement for each DTS object to class. 

• Since DTS objects can only have actions, you cannot code any attributes or 
events in your part information file. 

The following example shows a part information file, mydtsdt.vbe, that contains the 
information for the following sample DTS objects: 

MyDTSDate Returns the current date. 

MyDTSTime Returns the current time. 
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// 

// SOM classes as Visual Builder classes 

// 

//VBBeginPartlnfo: MyDTSDate, "My DTS SOM Date Class" 

//VBIncludes: "mydtsdat.hh" MyDTSDate_hh 
//VBPartDataFile: 'mydtsdt.vbb' 

//VBLibFile: 'mydtsdat.lib 1 
//VBComposerlnfo: class 
//VBAction: getTodaysDate 

//VB: ,"Get today's date action.",char*, 

//VB: char* getTodaysDate() 

//VBPreferredFeatures: this, getTodaysDate 
//VBEndPartlnfo: MyDTSDate 
// 

//VBBeginPartlnfo: MyDTSTime, "My DTS SOM Time Class" 

//VBIncludes: "mydtstim.hh" MyDTSTime_hh 
//VBPartDataFile: 'mydtsdt.vbb' 

//VBLibFile: 'mydtstim.1ib' 

//VBComposerlnfo: class 

//VBAction: getCurrentTime 

//VB: ,"Get current time action.",char*, 

//VB: char* getCurrentTime() 

//VBPreferredFeatures: this, getCurrentTime 
//VBEndPartlnfo: MyDTSTime 
// 

The mydtsdt.vbe file contains statements that refer to the following files that are 
needed for each of the sample DTS objects: 

mydtsdat.hh and mydtstim.hh 

The header files for the MyDTSDate and MyDTSTime SOM 
classes. 

mydtsdat.lib and mydtstim.lib 

The library files that were created when the DTS objects were 
compiled. 

mydtsdt.vbb The part (.vbb) file that is to contain the information about the DTS 
parts when you import the part information from the mydtsdt.vbe 
file. You must load the mydtsdt.vbb file into Visual Builder before 
you can add the MyDTSDate and MyDTSTime parts to the 
free-form surface in the Composition Editor. 

Once you create your part information file, you must import it into Visual Builder 
before you can use your DTS objects in a Visual Builder application. For 
information on how to do this, see “Importing Part Information” on page 117. 

The next step is using DTS objects in a Visual Builder application. 
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Using DTS Objects in a Visual Builder Application 

Using DTS objects in a Visual Builder application is no different from using a class 
interface part. You simply place the DTS objects on the free-form surface and make 
the necessary connections to use their actions. 

The following figure shows how we used the MyDTSDate and MyDTSTime objects 
in a simple application. 



Figure 118. Sample Application Using DTS Objects 

To create the application, we placed the MyDTSDate and MyDTSTime parts on the 
free-form surface by selecting Options^Add part and providing the necessary 
information in the Add Part window for each part. 

In this application, when a user clicks on the Current push button, the 
buttonClickEvent feature causes the getTodaysDate and getTodaysTime actions to get 
the date and time that is currently set in your computer’s operating system. In 
addition, the actionResult attribute of each connection updates the text attribute of 
each entry field with the result of the two actions, the current date and time. 

Earlier, we mentioned that actions in DTS classes can return only basic C data types. 
The getTodaysDate and getTodaysTime actions in our example both return a data type 
of char*. Therefore, when we connected the actionResult attribute to the text attribute 
of the entry field. Visual Builder displayed a message saying that the types did not 
match and asking if we wanted to continue. In this case, we could make the 
connection because IString has a constructor that takes a char*. You can find out 
whether to complete a connection in situations like this by looking at the IBM Open 
Class Library Reference. 
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When you have generated your code and are ready to compile your 
application, make sure you have the .hh and .lib files that contain the code 
for your DTS objects in the current directory. Also, make sure the SOM 
Toolkit is installed because the VisualAge C++ compiler must have access 
to several of its files. 

When you are ready to run your application, the .dll for the DTS objects 
must be accessible. 


Bypassing DTS Limitations 

Earlier, we told you that DTS objects have certain limitations, such as not being able 
to use attributes and events, and not being able to notify other parts. You can bypass 
these limitations by using nonvisual parts to manage the things your DTS objects 
cannot do. 

In the example shown in “Using DTS Objects in a Visual Builder Application” on 
page 304, we could have created two nonvisual parts called MyDate and MyTime in 
addition to the two DTS parts, MyDTSDate and MyDTSTime. We could give these 
nonvisual parts attributes such as theDate and theTime and notify other parts when the 
values of these attributes change. We could also give these attributes get and set 
member functions that call actions in the DTS objects to get and set the values of the 
attributes. 

Once this is done, we would place the nonvisual parts MyDate and MyTime on the 
free-form surface, instead of MyDTSDate and MyDTSTime, and make the same 
connections as described previously. 
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Glossary 


This glossary defines terms and abbreviations that are used in 
this book. If you do not find the term you are looking for, 
refer to the IBM Dictionary of Computing, New 
York:McGraw-Hill, 1994. 

This glossary includes terms and definitions from the 
American National Standard Dictionary for Information 
Systems, ANSI X3.172-1990, copyright 1990 by the 
American National Standards Institute (ANSI). Copies may 
be purchased from the American National Standards Institute, 
1430 Broadway, New York, New York 10018. 


A 

abstract class. A class that provides common behavior 
across a set of subclasses but is not itself designed to have 
instances that work. An abstract class represents a concept; 
classes derived from it represent implementations of the 
concept. For example, IControl is the abstract base class for 
control view windows; the ICanvas and IListBox classes are 
controls derived from IControl. An abstract class must have 
at least one pure virtual function. 

See also base class. 

access. A property of a class that determines whether a class 
member is accessible in an expression or declaration. 

action. A specification of a function that a part can perform. 
The visual builder uses action specifications to generate 
connections between parts. Actions are resolved to member 
function calls in the generated code. 

Compare to event and attribute. 

argument. A data element, or value, included as part of a 
member function call. Arguments provide additional 
information that the called member function can use to 
perform the requested operation. 

attribute. A specification of a property of a part. For 
example, a customer part could have a name attribute and an 
address attribute. An attribute can itself be a part with its 
own behavior and attributes. 

The visual builder uses attribute specifications to generate 
code to get and set part properties. 

Compare to event and action. 


attribute-to-action connection. A connection that starts an 
action whenever an attribute’s value changes. It is similar to 
an event-to-action connection because the attribute’s event ID 
is used to notify the action when the value of the attribute 
changes. 

See also connection. Compare to event-to-action connection. 

attribute-to-attribute connection. A connection from an 
attribute of one part to an attribute of another part. When 
one attribute is updated, the other attribute is updated 
automatically. 

See also connection. 

attribute-to-member function connection. A connection 
from an attribute of a part to a member function. The 
connected attribute receives its value from the member 
function, which can make calculations based on the values of 
other parts. 

See also connection. 

B 

base class. A class from which other classes or parts are 
derived. A base class may itself be derived from another 
base class. 

See also abstract class. 

behavior. The set of external characteristics that an object 
exhibits. 

C 

caller. An object that sends a member function call to 
another object. 

Contrast with receiver. 

category. In the Composition Editor, a selectable grouping 
of parts represented by an icon in the left-most column. 
Selecting a category displays the parts belonging to that 
category in the next column. 

See also parts palette. 

class. An aggregate that can contain functions, types, and 
user-defined operators, in addition to data. Classes can be 
defined hierarchically, allowing one class to be an expansion 
of another, and can restrict access to its members. 
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Class Editor. The editor you use to specify the names of 
files that Visual Builder writes to when you generate default 
code. You can also use this editor to do the following: 

• Enter a description of the part 

• Specify a different .vbb file in which to store the part 

• See the name of the part’s base class 

• Modify the part’s default constructor 

• Enter additional constructor and destructor code 

• Specify a .lib file for the part 

• Specify a resource DLL and ID to assign an icon to the 
part 

• Specify other files that you want to include when you 
build your application 

Compare to Composition Editor and Part Interface Editor. 

class hierarchy. A tree-like structure showing relationships 
among object classes. It places one abstract class at the top 
(a base class) and one or more layers of less abstract classes 
below it. 

class library. A collection of classes. 

class member function. See member function. 

client area object. An intermediate window between a 
frame window (IFrameWindow) and its controls and other 
child windows. 

client object. An object that requests services from other 
objects. 

collection. A set of features in which each feature is an 
object. 

Common User Access (CUA). An IBM architecture for 
designing graphical user interfaces using a set of standard 
components and terminology. 

composite part. A part that is composed of a part and one 
or more subparts. A composite part can contain visual parts, 
non visual parts, or both. 

See also nonvisual part, part, subpart, and visual part. 

Composition Editor. A view that is used to build a 
graphical user interface and to make connections between 
parts. 

Compare to Class Editor and Part Interface Editor. 

concrete class. A subclass of an abstract class that is a 
specialization of the abstract class. 

connection. A formal, explicit relationship between parts. 
Making connections is the basic technique for building any 


visual application because that defines the way in which parts 
communicate with one another. The visual builder generates 
the code that then implements these connections. 

See also attribute-to-action connection, attribute-to-attribute 
connection, attribute-to-member function connection, 
parameter connection, custom logic connection, 
event-to-action connection, event-to-attribute connection, and 
event-to-member function connection. 

const. An attribute of a data object that declares that the 
object cannot be changed. 

construction from parts. A software development 
technology in which applications are assembled from existing 
and reusable software components, known as parts. 

constructor. A special class member function that has the 
same name as the class and is used to construct and possibly 
initialize class objects. 

CUA. See Common User Access. 

cursored emphasis. When the selection cursor is on a 
choice, that choice has cursored emphasis. 

custom logic connection. A connection that causes your 
customized C or C++ code to be run. This connection can be 
triggered either when an attribute’s value changes or an event 
occurs. 

D 

data abstraction. A data type with a private representation 
and a public set of operations. The C++ language uses the 
concept of classes to implement data abstraction. 

data member. Private data that belongs to a given object 
and is hidden from direct access by all other objects. Data 
members can only be accessed by the member functions of 
the defining class and its subclasses. 

data model. A combination of the base classes and parts 
shipped with the product and the classes and parts you save 
and create. They are saved in a file named vbbase.vbb. 

data object. A storage area used to hold a value. 

declaration. A description that makes an external object or 
function available to a function or a block. 

DEF file. See module definition file. 

derivation. The creation of a new or abstract class from an 
existing or base class. 
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destructor. A special class member function that has the 
same name as the class and is used to destruct class objects. 

DLL. See dynamic link library. 

dynamic link library (DLL). In OS/2, a library containing 
data and code objects that can be used by programs or 
applications during loading or at run time. Although they are 
not part of the program’s executable (.exe) file, they are 
sometimes required for an .exe file to run properly. 

E 

encapsulation. The hiding of a software object’s internal 
representation. The object provides an interface that queries 
and manipulates the data without exposing its underlying 
structure. 

event. A specification of a notification from a part. 

Compare to action, attribute, and part event. 

event-to-action connection. A connection that causes an 
action to be performed when an event occurs. 

See also connection. 

event-to-attribute connection. A connection that changes 
the value of an attribute when a certain event occurs. 

See also connection. 

event-to-member function connection. A connection from 
an event of a part to a member function. When the 
connected event occurs, the member function is executed. 

See also connection. 

expansion area. The section of a multicell canvas between 
the current cell grid and the outer edge of the canvas. 
Visually, this area is bounded by the rightmost column 
gridline and the bottommost row gridline. 

F 

feature. (1) A major component of a software product that 
can be installed separately. (2) In Visual Builder, an action, 
attribute, or event that is available from a part’s part interface 
and that other parts can connect to. 

full attribute. An attribute that has all of the behaviors and 
characteristics that an attribute can have: a data member, a 
get member function, a set member function, and an event 
identifier. 


free-form surface. The large open area of the Composition 
Editor window. The free-form surface holds the visual parts 
contained in the views you build and representations of the 
nonvisual parts (models) that your application includes. 

G 

graphical user interface (GUI). A type of interface that 
enables users to communicate with a program by 
manipulating graphical features, rather than by entering 
commands. Typically, a graphical user interface includes a 
combination of graphics, pointing devices, menu bars and 
other menus, overlapping windows, and icons. 

GUI. See graphical user interface. 

H 

handles. Small squares that appear on the comers of a 
selected visual part in the visual builder. Handles are used to 
resize parts. 

Compare to primary selection. 

header file. A file that contains system-defined control 
information that precedes user data. 

I 

inheritance. (1) A mechanism by which an object class can 
use the attributes, relationships, and member functions 
defined in more abstract classes related to it (its base classes). 
(2) An object-oriented programming technique that allows 
you to use existing classes as bases for creating other classes. 

instance. Synonym for object, a particular instantiation of a 
data type. 

L 

legacy code. Existing code that a user might have. Legacy 
applications often have character-based, nongraphical user 
interfaces; usually they are written in a nonobject-oriented 
language, such as C or COBOL. 

loaded. The state of the mouse pointer between the time 
you select a part from the parts palette and deposit the part 
on the free-form surface. 
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M 

main part. The part that users see when they start an 
application. This is the part from which the main() function 
C++ code for the application is generated. 

The main part is a special kind of composite part. 

See also part and subpart. 

member. (1) A data object in a structure or a union. (2) In 
C++, classes and structures can also contain functions and 
types as members. 

member function. An operator or function that is declared 
as a member of a class. A member function has access to the 
private and protected data members and member functions of 
objects of its class. 

member function call. A communication from one object to 
another that requests the receiving object to execute a 
member function. 

A member function call consists of a member function name 
that indicates the requested member function and the 
arguments to be used in executing the member function. The 
member function call always returns some object to the 
requesting object as the result of performing the member 
function. 

Synonym for message. 

member function name. The component of a member 
function call that specifies the requested operation. 

message. A request from one object that the receiving object 
implement a member function. Because data is encapsulated 
and not directly accessible, a message is the only way to send 
data from one object to another. Each message specifies the 
name of the receiving object, the member function to be 
implemented, and any arguments the member function needs 
for implementation. 

Synonym for member function call. 

model. A nonvisual part that represents the state and 
behavior of a object, such as a customer or an account. 

Contrast with view. 

module definition file. A file that describes the code 
segments within a load module. 

Synonym for DEF file. 


N 

nested class. A class defined within the scope of another 
class. 

nonvisual part. A part that has no visual representation at 
run time. A nonvisual part typically represents some 
real-world object that exists in the business environment. 

Compare to model. Contrast with view and visual part. 

no-event attribute. An attribute that does not have an event 
identifier. 

no-set attribute. An attribute that does not have a set 
member function. 

notebook part. A visual part that resembles a bound 
notebook containing pages separated into sections by tabbed 
divider pages. A user can turn the pages of a notebook or 
select the tabs to move from one section to another. 

O 

object. (1) A computer representation of something that a 
user can work with to perform a task. An object can appear 
as text or an icon. (2) A collection of data and member 
functions that operate on that data, which together represent a 
logical entity in the system. In object-oriented programming, 
objects are grouped into classes that share common data 
definitions and member functions. Each object in the class is 
said to be an instance of the class. (3) An instance of an 
object class consisting of attributes, a data structure, and 
operational member functions. It can represent a person, 
place, thing, event, or concept. Each instance has the same 
properties, attributes, and member functions as other instances 
of the object class, though it has unique values assigned to its 
attributes. 

object class. A template for defining the attributes and 
member functions of an object. An object class can contain 
other object classes. An individual representation of an 
object class is called an object. 

object factory. A nonvisual part capable of dynamically 
creating new instances of a specified part. For example, 
during the execution of an application, an object factory can 
create instances of a new class to collect the data being 
generated. 

object-oriented programming. A programming approach 
based on the concepts of data abstraction and inheritance. 
Unlike procedural programming techniques, object-oriented 
programming concentrates on those data objects that comprise 
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the problem and how they are manipulated, not on how 
something is accomplished. 

observer. An object that receives notification from a notifier 
object. 

operation. A member function or service that can be 
requested of an object. 

overloading. An object-oriented programming technique that 
allows you to redefine functions and most standard C++ 
operators when the functions and operators are used with 
class types. 

P 

palette. See parts palette. 

parameter connection. A connection that satisfies a 
parameter of an action or member function by supplying 
either an attribute’s value or the return value of an action, 
member function, or custom logic. The parameter is always 
the source of the connection. 

See also connection. 

parent class. The class from which another part or class 
inherits data, member functions, or both. 

part. A self-contained software object with a standardized 
public interface, consisting of a set of external features that 
allow the part to interact with other parts. A part is 
implemented as a class that supports the INotifier protocol 
and has a part interface defined. 

The parts on the palette can be used as templates to create 
instances or objects. 

part event. A representation of a change that occurs to a 
part. The events on a part's interface enable other interested 
parts to receive notification when something about the part 
changes. For example, a push button generates an event 
signaling that it has been clicked, which might cause another 
part to display a window. 

part event ID. The name of a part static-data member used 
to identify which notification is being signaled. 

part interface. A set of external features that allows a part 
to interact with other parts. A part’s interface is made up of 
three characteristics: attributes, actions, and events. 

Part Interface Editor. An editor that the application 
developer uses to create and modify attributes, actions, and 
events, which together make up the interface of a part. 


Compare to Class Editor and Composition Editor. 

parts palette. The parts palette holds a collection of visual 
and nonvisual parts used in building additional parts for an 
application. The parts palette is organized into categories. 
Application developers can add parts to the palette for use in 
defining applications or other parts. 

preferred features. A subset of the part’s features that 
appear in a pop-up connection menu. Generally, they are the 
features used most often. 

primary selection. In the Composition Editor, the part used 
as a base for an action that affects several parts. For 
example, an alignment tool will align all selected parts with 
the primary selection. Primary selection is indicated by 
closed (solid) selection handles, while the other selected parts 
have open selection handles. 

See also selection handles. 

private. Pertaining to a class member that is accessible only 
to member functions and friends of that class. 

process. A program running under OS/2, along with the 
resources associated with it (memory, threads, file system 
resources, and so on). 

program. (1) One or more files containing a set of 
instructions conforming to a particular programming language 
syntax. (2) A self-contained, executable module. Multiple 
copies of the same program can be run in different processes. 

protected. Pertaining to a class member that is only 
accessible to member functions and friends of that class, or to 
member functions and friends of classes derived from that 
class. 

prototype. A function declaration or definition that includes 
both the return type of the function and the types of its 
arguments. 

primitive part. A basic building block of other parts. A 
primitive part can be relatively complex in terms of the 
function it provides. 

process. A collection of code, data, and other system 
resources, including at least one thread of execution, that 
performs a data processing task. 

property. A unique characteristic of a part. 

pure virtual function. A virtual function that has a function 
definition of = 0;. 
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R 

receiver. The object that receives a member function call. 
Contrast with caller. 

resource file. A file that contains data used by an 
application, such as text strings and icons. 

S 

selection handles. In the Composition Editor, small squares 
that appear on the corners of a selected visual part. Selection 
handles are used to resize parts. 

See also primary selection. 

server. A computer that provides services to multiple users 
or workstations in a network; for example, a file server, a 
print server, or a mail server. 

service. A specific behavior that an object is responsible for 
exhibiting. 

settings view. A view of a part that provides a way to 
display and set the attributes and options associated with the 
part. 

sticky. In the Composition Editor, the mode that enables 
you to add multiple parts of the same class (for example, 
three push buttons) without going back and forth between the 
parts palette and the free-form surface. 

structure. A construct that contains an ordered group of 
data objects. Unlike an array, the data objects within a 
structure can have varied data types. 

subpart. A part that is used to create another part. 

See also nonvisual part, part, and visual part. 

superclass. See abstract class and base class. 

T 

tear-off attribute. An attribute that an application developer 
has exposed to work with as though it were a stand-alone 
part. 

template. A family of classes or functions with variable 
types. 

thread. A unit of execution within a process. 


tool bar. The strip of icons along the top of the free-form 
surface. The tool bar contains tools to help you construct 
composite parts. 

U 

UI. See user interface. 

unloaded. The state of the mouse pointer before you select 
a part from the parts palette and after you deposit a part on 
the free-form surface. In addition, you can unload the mouse 
pointer by pressing the Esc key. 

user interface (UI). (1) The hardware, software, or both 
that enable a user to interact with a computer. (2) The term 
user interface normally refers to the visual presentation and 
its underlying software with which a user interacts. 

V 

variable. (1) A storage place within an object for a data 
feature. The data feature is an object, such as number or 
date, stored as an attribute of the containing object. (2) A 
part that receives an identity at run time. A variable by itself 
contains no data or program logic; it must be connected such 
that it receives runtime identity from a part elsewhere in the 
application. 

view. (1) A visual part, such as a window, push button, or 
entry field. (2) A visual representation that can display and 
change the underlying model objects of an application. 

Views are both the end result of developing an application 
and the basic unit of composition of user interfaces. 

Compare to visual part. Contrast with model. 

virtual function. A function of a class that is declared with 
the keyword virtual. The implementation that is executed 
when you make a call to a virtual function depends on the 
type of the object for which it is called. This is determined 
at run time. 

visual part. A part that has a visual representation at run 
time. Visual parts, such as windows, push buttons, and entry 
fields, make up the user interface of an application. 

Compare to view. Contrast with nonvisual part. 

visual programming tool. A tool that provides a means for 
specifying programs graphically. Application programmers 
write applications by manipulating graphical representations 
of components. 
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w 

white space. Space characters, tab characters, form-feed 
characters, and new-line characters. 


window being on top of another. (2) In the Composition 
Editor, a window is a part that can be used as a container for 
other visual parts, such as push buttons. 


window. (1) A rectangular area of the screen with visible 
boundaries in which information is displayed. Windows can 
overlap on the screen, giving it the appearance of one 
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Special Characters 

.LIB file name field 54 
# preceding code string 145 
#ifndef macro 57 
#ifndef statement 57 
#include statement 57 

A 

abstract class 88 
accessibility 184 
action 

adding 70 
changing 72 
defined 4 
deleting 72 
setting defaults for 72 
updating 72 

activate settings changes 146 
add 

action 70 

add rows and columns to multicell canvas 225, 
attribute 59 

categories and parts to parts palette 285 

category to parts palette 287 

code to a part 105 

code to set attribute 113 

container column 238 

container parts 235 

dynamic parts to the primary part 266 

event 65 

menu bar 246 

menu choices 247 

menus to application 245 

message box 209 

nonvisual parts to the primary part 265 

Object Factory part 267 

pages to notebook 242 

part selected in Visual Builder window 289 

part to parts palette 289 

part when editing 290 

part with loaded .vbb file 291 

preferred feature 77 

static parts to the primary part 266 

variable to support Object Factory 268 


add variable 

to composite part 163 
to free-form surface 164 
to part interface 165 
Align Bottom 46, 139 
Align Center 45, 139 
align fields 15 
Align Left 45, 139 
Align Middle 45, 139 
align parts 13, 43, 139 
Align Right 45, 139 
Align Top 45, 139 
aligning fields 15 
anchor part 132 
application 

adding menus 245 
aligning parts 13 
building 21, 218 
bypassing DTS limitations 305 
centering fields in 15 
centering push buttons 16 
compiling and linking 276 
i, 233 composing parts 42 

connecting parts 16 
creating simple 7 
designing parts 83 
dragging and dropping parts 14 
generating code 217 
generating source code 20, 217, 271 
OASearch 90, 204 
object-oriented approach to 84 
placing parts 11 
resizing parts 13 
resizing window 14 
running 22, 218 
sample 90 

scanning for common elements 88 
setting up your WorkFrame project 25 
spacing push buttons 16 
to-do list 7 

using DTS objects in 304 
argument, connection 183 
arrange parts 137 
arrows 

bidirectional, cyan 167 
bidirectional, violet 173 
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arrows (continued) 
hollow 175 
solid 175 

unidirectional, blue 172 
unidirectional, dark green 168, 169, 171 
unidirectional, light green 170, 171 
Asian languages, DBCS support 299 
aText parameter 60 
attribute 

adding 59 

adding code to set 113 
behavior 58 
changing 62 

connections that use as source 61 

defined 4 

deleting 62 

description 61 

event identification 61 

example of 63 

full 58 

get member function 60 
name 59 
no-event 59 
no-set 59 

set member function 60 
setting defaults for 62 
tear-off 159, 164 
type 59 
updating 62 
attribute-to-action 5 
attribute-to-attribute 4 
attribute-to-member function 5 

B 

background, reverse color 133 
base class 
of part 53 
showing 36 

base class — access level field 53 
base class field 10, 120 
base files, showing 36 
behavior 

attribute 58 
factoring common 88 
bounding box, space parts within 140 
bracket, square 164 
browse part information 187 
browser option 275 


browsing features 176 
building application 21, 218 
Buttons category 47 

C 

C++ code file field 55 
C++ header file field 55 
canvas, adjust size 298 
category 

adding to parts palette 285, 287 
deleting from parts palette 292 
parts 130 

removing from parts palette 292 
saving changes 292 
category, save 288 
center 

push buttons 16 
within application window 15 
change 

action 72 

activate settings 146 

adding menus to application 245 

arrange parts 137 

attribute 62 

constructor 53 

constructor code 54 

destructor code 54 

event 67 

feature code, generated 109 
font for part 144 
groups 151 
information area 36 
labels 162 
match part size 139 
move part 137 

part name on the free-form surface 136 

parts on free-form surface 153 

parts palette, save 292 

position part on grid 137 

promoted feature 74 

redo 160 

settings 162 

settings for a connection 194 
settings for a part 140 
size part 138 

source and target of connection 203 
tab order 148, 149 
tab stops 151 

title of to-do list window 10 
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change (continued) 
undo 160 
variable type 164 
class 

abstract 88 
repository 88 

use interface parts to represent data 115 
Class Editor 

base class of part 53 
describing a part 52 
description of 41 
icon, specifying 55 
including 

files in application 56 
part in .vbb file 53 
library file, specifying 54 
modifying part constructor 53 
naming code generation file 55 
specifying 
files 51 

starting resource ID 54 
your own constructor code 54 
your own destructor code 54 
class name field 9, 119 
clear 

action page fields 73 
attribute page fields 63 
event page fields 67 
promote page fields 75 
clipboard, copy part 134 
code generation file, naming 55 
code string, precede with # 145 

code, generating 20, 217 
color 

of part 144 
reverse 133 
Color page 144 
colored connection line 179 
column, add container 238 
common behavior, factoring 88 
compilation, preparing files for 275 
compiler program 

browser option 275 
debug options 275 
compiling application 276 
components, suggested size 89 
compose parts of application 42 
Composers category 49 
Composers part, spacing parts within 140 


composite part 

adding a variable 163 
aligning parts within 43 
creating 130 
example of 183 
Composition Editor 
components 

free-form surface 50 
parts palette 46 
tool bar 43 
description of 41 
exiting 23 

undoing and redoing changes 160 
concepts 

connections 4 
parts 4 

source code generation 5 
connect 

exception events to actions and member functions 192 

features to custom logic 188 

features to features 178 

features to member functions 183 

Object Factory part 268 

parts 16 

parts to fill container 240 
variable part 206 

variable to corresponding Object Factory part 268 
connecting part to variable that represents it 270 
connection 

attribute-to-action 170 

attribute-to-attribute 167 

attribute-to-member function 171 

between parts 43 

call customized code 174 

cause one data value to change another 174 

change a data value whenever an event occurs 174 

change source and target 203 

colored line 179 

custom logic 172, 189 

delete 200 

deselect 203 

end points 203 

event to member function 184 

event-to-action 169 

event-to-attribute 168 

event-to-member 170 

hide 200 

invoke a member function whenever a data value 
changes 174 

invoke a member function whenever an event 
occurs 174 
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connection (continued) 

invoke an action whenever a data value changes 174 
invoke an action whenever an event occurs 174 
making 175 
manipulate 194 
menu 17 

modal window 268 
modeless window 269 
OASearch application 204 
open settings window 194 
rearrange 202 
reorder 199 

satisfy a parameter with a data value 175 
select 202 
show 200 

source and target 175 
source features 194 
target features 194 
type summary 174 
using 167 
using attribute 61 
constant value 181 
construct 

application, visually 115 
user interface 161 
constructor 

modifying 53 
specifying your own 54 
constructor field 53 
container 

adding columns 238 
adding nonvisual part 239 
connecting parts to fill 240 
constructing 235 
parts, adding 235 
populating collection 239 
title 237 

type and layout 237 
contract.cpv file 90 
contrctr.cpv file 90 
Control page 141 
convention, naming 91 
copy part 

by dragging 134 
to another .vbb file 123 
with clipboard 134 
cpp field 55 
cpv files for OASearch 
contract.cpv 90 
contrctr.cpv 90 


cpv files for OASearch (continued) 
skillb.cpv 90 
create 

application 

files, including 56 
simple 7 
source code 271 
to-do list 7 
building 21, 218 
compiling and linking 276 
make files 39 
new part 119 
part 

add several copies 127 
adding code 105 
basic steps 119 
composite 130 
connecting 16 
defining interface 101 
derived 86 

description, entering 52 
designing for single purpose 83 
generating default feature code 106 
guidelines for placing 129 
icon, specifying 55 
library file, specifying 54 
nonvisual 101 
placing in window 11 
similar to another 86 
source code 271 

starting resource ID, specifying 54 
visual for to-do list 9 
running 22, 218 

setting up your WorkFrame project 25 
crosshairs 11 
custom logic 5 

customizing the information area 36 


D 

dashed line 179 
Data entry category 47 
data types 
delete 37 

export definitions 37 
IStandardNotifier* 59 
IString 59 
move 37 
undefined 60 
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DBCS support for Asian languages 299 

dde4vr30.dll resource file 287 

debug options 275 

default push button 163 

defaults, parameters 182 

define part interface 281 

delete 

action 72 
attribute 62 

category from parts palette 292 

connection 200 

data types 37 

event 67 

part 

from .vbb file 125 
from free-form surface 135 
from parts palette 292 
promoted feature 75 

rows and columns from multicell canvas 226 
undo 135 
derived part 86 
description field 9, 52, 119 
description of part, entering 52 
description, showing 36 
deselect 

all parts 116 
connections 203 
files 35 
part 133 

designing applications 83 
destructor, specifying your own 54 
determine source and target 175 
direct editing 136 
display part names 115 
display pop-up menu 134 
display, refreshing 40 
Distribute Horizontally 46, 140 
Distribute Vertically 46, 140 
DLL name field 55 
drag part to copy 134 
dragging parts 14 
dropping parts 14 
DTS objects 

bypassing limitations 305 

using in a Visual Builder application 304 

E 

edit 

adding part being edited to parts palette 290 


edit (continued) 

parts on free-form surface 153 
text string 135 
editor 

symbols 

Class Editor 41 
Composition Editor 41 
Part Interface Editor 42 
end 

Composition Editor 23 
Visual Builder 23 
entry field 

aligning edges 15 
centering in window 15 
matching width with list box 13 
placing in window 11 
event 

adding 65 
changing 67 
defined 4 
deleting 67 
description 66 
example of 68 
identification 66 
name 66 
parameters 66 
ready event 65 
setting defaults for 67 
updating 67 
event-to-action 5 
event-to-attribute 5 
event-to-member function 5 
examples 

attribute 63 
event 68 
OAContractor 101 
exception event 192 
exception handler 192 
exception, pass to message box 209 
existing code, use with Visual Builder 281 
exit 

Composition Editor 23 
Visual Builder 23 
export data type definitions 37 
export interface 118 
export part information 118 
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F 

FAT file names 38 
feature 

browsing 176 
connecting 178 
Part Interface Editor 57 
promoting from Composition Editor 155 
promoting from Part Interface Editor 74 
feature code, changing 109 
feature source pull-down 107 
field value, supply 145 
fields 

.LIB file name 54 

aligning 15 

base class 10, 120 

base class — access level 53 

C++ code file 55 

C++ header file 55 

centering in application window 15 

class name 9, 119 

constructor 53 

cpp 55 

description 9, 52, 119 
DLL name 55 
file name 9, 119 
handler name 142 
hpp 55 
limit 145 

part file specification 53 
part type 10, 120 
required include files 56 
resource ID 55 
source part name 123 
starting resource id 54, 297 
target file name 123 
target part name 123 
user .cpv file 56 
user .h file 56 
user .hpv file 56 
user .rev file 56 
file name field 9, 119 
file name, showing 36 
files 

.vbb 33 

cpv files for OASearch 
contract.cpv 90 
contrctr.cpv 90 
skillb.cpv 90 

creating SOM part information 302 


files (continued) 

dde4vr30.dll 287 
deselecting 35 
external references 275 
loading 33 
names, using FAT 38 
part 33 
selecting 35 
todolist.app 21 
todolist.cpp 21 
todolist.exe 21 
todolist.h 21 
todolist.hpp 21 
todolist.mak 21 
todolist.map 21 
todolist.o 21 
todolist.obj 22 
todolist.rc 21 
todolist.res 22 
todolst2.app 218 
todolst2.cpp 217 
todolst2.exe 218 
todolst2.h 217 
todolst2.hpp 217 
todolst2.mak 218 
todolst2.map 218 
todolst2.o 218 
todolst2.obj 218 
todolst2.rc 217 
todolst2.res 218 
unloading 34 
vbb 

deselecting 35 
include part 53 
loading 33 
move part 53 
oanonvis 90, 161 
oawin 90 
selecting 35 
unloading 34 
vbbase.vbb 32 
VBCC.vbb 32 
VBMM.vbb 32 
vbsample.vbb 32 
vbbase.vbb 4 
vbpalet.dat 292 

files, including in application 56 

Font page 144 

Frame Extensions category 48 
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free-form surface 50 
add message box 209 
editing part 153 
placing part on 127 
full attribute 58 
full file names, showing 37 

G 

General page 141 
generate 

code for application 20, 217 
generating default feature code 106 
make files 39, 271 
part source code from visual tool 43 
preparing files for compilation 275 
source code for applications 271 
source code for main() function 274 
source code for parts 271, 272 
source code for visual part 20, 217 
source files created 273 
generate all push button 108 
generic settings notebook 146 
graphical user interface (GUI) 
adding basic visual parts 161 
changing labels 162 
changing settings 162 
construct 115 

construct for application 161 
mnemonic 162 

push button with mnemonic 162 
specify default push button 163 
grid 

hide 138 
position part 137 
show 138 
spacing 138 
group box 

color area 144 
icon 55 

minimum size 144 
user files included in generation 56 
groups, setting 151 
GUI 

See graphical user interface (GUI) 
guidelines 

placing parts 129 

setting groups and tab stops 152 


H 

Handlers page 142 
help 

context-sensitive 254 
fly-over help 259 

for frame windows generated by object factory 258 
general 255 
help push button 258 
help window 256 
information area 261, 262, 263 
introduction to 251, 301 
help file 

building 253 
creating 252 
Hide Connections 44, 200 
hide grid 138 

highlighting conventions xiv 
How Do I, how to use xvi 
hpp field 55 

I 

IBM Open Class Library 4 
icon 

preparing for parts palette 285 
specifying for category 287 
specifying for part 55, 288 
identify reusable parts 85 
ifndef macro 57 
ifndef statement 57 
IFrameWindow 10 
import part information 117, 283 
include statement 57 
index cards, using 90 
information area 261, 262, 263 
base class 36 
customizing 36 
description 36 
file name 36 
inheritance, using 86 
invalid parameters 183 
IStandardNotifier, default data type 59 
IString, data type 59 

L 

language friendly applications 293 
layout, notebook 241 
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learning to use parts 115 
leave 

Composition Editor 23 
Visual Builder 23 
library file 

specifying in Class Editor 54 
specifying in make file 275 
limit field default 145 
line, dashed 179 
link 

See connection 

linker program, debug options 275 
linking application 276 
list box 

aligning edges 15 
centering in window 15 
colors 144 

connecting to Add push button 17 
connecting to Remove push button 19 
handler list 143 
Loaded Type Information 37 
matching width with entry field 13 
placing in window 12 
Lists category 48 
loaded .vbb file, add part 291 
Loaded Type Information list box 37 
loading files 33 
logic error 192 

M 

make file 

generating 39 
specifying library 275 
makemake program, WorkFrame 272 
making connections 175 
manipulate 

connections 194 
parts 134 

Match Height 46, 139 
match part size 139 
Match Width 46, 139 
menu 

adding menu bar 246 

adding menu choices 247 

adding to application 245 

connecting menu items in primary part 270 

items 245 

types 245 


message box 

add to free-form surface 209 
passing exceptions 209 
missing parameters 183 
mnemonic 162 
modal window connection 268 
modeless window connection 269 
Models category 50 
mouse pointer, unloading 43, 127 
move 

data types 37 
part 123, 137 

through settings notebook 141 
multicell canvas 221 
multiple selection 132 

N 

naming code generation file 55 
naming convention 91 
national language support 

adjust size for translated text 298 
country-sensitive format 298 
DBCS support for Asian languages 299 
enable 293 

resource files for translation, using 293 
rule of thumb 293 

navigate through settings notebook 141 
NLS 

See national language support 
no-event attribute 59 
no-set attribute 59 
nonvisual part 
See also part 
adding code 105 
adding to container 239 
creating 101 
defining interface 101 
direct edit 136 

generating default feature code 106 
oanonvis.vbb 90 
use to represent data 115 
notebook 

add pages 242 
add part 240 
add part to page 242 
generic settings 146 
layout 241 
page 242 

Part Interface Editor 57 
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notebook (continued) 
settings 140 
tab 242 

O 

OAContractor example part 101 
oanonvis.vbb 90, 161 
OASearch application 204 

adding nonvisual parts to the primary part 265 

adding OAGenlnfo to OAMain 266 

adding Object Factory parts 267 

adding variables to OAMain 268 

connecting from the Edit submenu 270 

connecting from the View submenu 270 

connecting nonvisual parts to promoted variables 270 

connecting Object Factory parts to frame window 268 

design 90 

integrating 265 

modal window connections 268 
modeless window connections 269 
setting Object Factory parts 267 
oawin.vbb 90 
object factory 
adding 267 
adding variable 268 
connecting 268 

connecting a variable to Object Factory part 268 
description 266 
setting 267 
object files, order 275 
object-oriented approach to design 84 
open area, large 50 
open part 121 
Open push button 10 
open settings notebook 140 
open settings window 194 
order, tab 148, 149 
Other category 50 
outline of part 127 
overlaying parts 129 


parameters (continued) 
satisfy 181 

part 

See also visual part, nonvisual part 

add several copies 127 

add to notebook page 242 

add to parts palette 289 

add when editing 290 

adding code 105 

adding to GUI 161 

adding to parts palette 285 

align 139 

aligning 13 

anchor 132 

arrange 137 

base 4 

base class 53 

browsing information 187 

buttons part 155 

category 130 

change positions in tabbing order 149 
color 144 
composing 42 

composite, add variable to 163 

connect to fill container 240 

connecting 16 

connecting to a variable 206 

connections between 43 

constructor, modifying 53 

constructor, specifying your own code 54 

container, add 235 

copy by dragging 134 

copy to another .vbb file 123 

copy using clipboard 134 

country-sensitive format 298 

creating new 119 

creating similar to another 86 

define interface 281 

defining interface 101 

delete from .vbb file 125 

delete from free-form surface 135 

delete from parts palette 292 


p 

derived 86 

description, entering 52 

pages, add notebook 242 

deselect all 116 

parameter connections 5 

deselecting 133 

parameters 

designing 90 

defaults 182 

designing for single purpose 83 

invalid 183 

destructor, specifying your own code 

missing 183 

display names 115 


54 
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part (continued) 

display pop-up menu 134 
dragging and dropping 14 
edit text string 135 
entry field 11 
entry field, width 13 
exporting information 118 
font, specify 144 

frame window with buttons part 155 

generating default feature code 106 

grid spacing 138 

guidelines for placing 129 

icon, specifying 55 

import 283 

importing information 117 
include in .vbb file 53 
learning to use 115 
library file, specifying 54 
list box 12 
list box, width 13 
manipulating 134 
match size 139 
move 53, 137 

move to different .vbb file 123 
notebook, add 240 
OASearch application 90 
open 121 

open settings notebook 140 
outline 127 
overlaying 129 
paste using clipboard 134 
placing 127 

placing in application window 11 

placing on the free-form surface 127 

position on grid 137 

promoting features 155 

push button, width 14 

push buttons 12 

remove 288 

removing 292 

rename in .vbb file 126 

rename on the free-form surface 136 

resizing 13 

save 288 

select all 116 

select multiple 133 

select single 133 

selected in Visual Builder window 289 
selecting 132 
settings notebook 141 


part (continued) 
size 138 

size more than one 139 

space in composers parts 140 

space within bounding box 140 

starting resource ID, specifying 54 

static text, placing 11 

supplementary composite, placing 130 

tear-off attribute 159 

toggle 138 

undo delete 135 

visual 9 

work with in Visual Builder window 115 
Part — New window 

base class field 10, 120 
class name field 9, 119 
description field 9, 119 
file name field 9, 119 
Open push button 10 
part type field 10, 120 
part code generation tool 44 
part file specification field 53 
part files 33 
part information file 117 
part information files 

creating for SOM objects 302 
creating for Visual Builder parts 281 
Part Interface Editor 
action page 69 

adding an action 70 
changing an action 72 
clearing the fields 73 
deleting an action 72 
setting defaults for an action 72 
updating an action 72 
attribute page 58 

adding an attribute 59 
an attribute example 63 
changing an attribute 62 
clearing the fields 63 
deleting an attribute 62 
setting defaults for an attribute 62 
updating an attribute 62 
components 

action member function 71 
action name 71 
description 66, 71 
event identification 66 
event name 66 
parameter names table 71 
parameters 66 
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Part Interface Editor (continued) 
components (continued) 
return type 71 
defining interface 102 
description of 42 
event page 64 

adding an event 65 
an event example 68 
changing an event 67 
clearing the fields 67 
deleting an event 67 
setting defaults for an event 67 
updating an event 67 
features 57 
preferred page 75 

adding a preferred feature 77 
removing a preferred feature 77 
removing all preferred features 78 
showing inherited preferred feature 78 
promote page 73 

changing a promoted feature 74 
clearing the promote page fields 75 
deleting a promoted feature 75 
promoting a feature 74 
updating a promoted feature 74 
part interface, add variable 165 
part type field 10, 120 
parts palette 46 
add part 289 

adding categories and parts 285 

Buttons category 47 

Composers category 49 

Data entry category 47 

Frame Extensions category 48 

Lists category 48 

Models category 50 

Other category 50 

placing a part 127 

prepare icon 285 

saving changes 292 

Sliders category 49 

sticky 127 

unique icon 288 

pass exception to message box 209 
paste part with clipboard 134 
placing parts on the free-form surface 127 
placing supplementary composite parts 130 
pop-up menu, display 134 
populate collection in container 239 


position parts 

on free-form surface 139 
on grid 137 
preferred features 
adding 77 
defined 178 
removing 77 
removing all 78 
showing inherited 78 
prerequisite knowledge xii 
promote page fields, clearing 75 
promote part feature 156 
promoted features 
changing 74 
deleting 75 
updating 74 

promoting part features 74, 155 
pull down 

feature source 107 
push button 

Add with defaults 60 
aligning edges 15 
calculate 170 
centering 16 

connecting Add to list box 17 

connecting Remove to list box 19 

default, specify 163 

Defaults 60 

enable 204 

generate all 108 

matching widths 14 

mnemonic, with 162 

Open 10 

placing in window 12 
spacing evenly across window 16 

Q 

quit 

Composition Editor 23 
Visual Builder 23 

R 

ready event 65 
rearrange connections 202 
recruitment application, user interface 161 
red-green-blue values 144 
redo changes 160 


Index 
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refreshing the display 40 
remove 

all preferred features 78 
category or part 292 
preferred feature 77 
remove category 288 
rename part in .vbb file 126 
rename part on the free-form surface 136 
reorder connections 199 
repository for common member function 88 
required include files field 56 
resize 

See size 

resource ID field 55 
reusable part 
identify 85 
reuse, components 89 
reverse color 133 
RGB values 144 
running application 22, 218 

S 

sample, 00 application 84 
save changes, parts palette 292 
scan for common elements 88 
select 

all parts 116 
connections 202 
multiple part 133 
part 132 
part files 35 
single part 133 
selection handles 132 
selection tool 44 
Set Grid Spacing 138 
setting an Object Factory part 267 
setting defaults 

for an action 72 
for an attribute 62 
for an event 67 

setting up your WorkFrame project 25 
settings 

activating changes 146 
for a connection, changing 194 
for a part, changing 140 
settings notebook 
generic 146 
navigating 141 


Show Connections 44, 200 
show grid 138 

show inherited preferred features 78 
size 

application window 14 
entry field, width 13 
list box, width 13 
match part 139 
more than one part 139 
parts 13, 138 
push button, width 14 
Size/Position page 144 
skillb.cpv file 90 
Sliders category 49 
Snap To Grid 45 
snap to grid tool 137 
SOM objects 301 
source code generation 271 
source files 273 
source of connection 175 
changing 203 
space part 

within bounding box 140 
within Composers part 140 
spacing, grid 138 
special notices x 
square bracket symbols 164 
start 

application 22, 218 
Visual Builder from OS/2 26 
Visual Builder from tools folder 8, 27 
Visual Builder from WorkFrame 27 
starting resource ID 54, 297 
static text 

aligning edges 15 
placing in window 11 
Styles page 141 
symbols 

Class Editor 41 
Composition Editor 41 
Part Interface Editor 42 
system error 192 

T 

tab order 148, 149 
tab stops, setting 151 
Tabbing And Depth Order 148 
target of connection 175 
changing 203 
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tear off an attribute 159 
tear-off attribute 164 
text string, edit 135 
title, changing on to-do list window 
to-do list 
changing 

title of window 10 
creating 

application 7 
visual part, new 9 
todolist.app 21 
todolist.cpp 21 
todolist.exe 21 
todolist.h 21 
todolist.hpp 21 
todolist.mak 21 
todolist.map 21 
todolist.o 21 
todolist.obj 22 
todolist.rc 21 
todolist.res 22 
todolst2.app 218 
todolst2.cpp 217 
todolst2.exe 218 
todolst2.h 217 
todolst2.hpp 217 
todolst2.mak 218 
todolst2.map 218 
todolst2.o 218 
todolst2.obj 218 
todolst2.rc 217 
todolst2.res 218 
Toggle Grid 45, 138 
tool bar 

Align Bottom 46, 139 
Align Center 45, 139 
Align Left 45, 139 
Align Middle 45, 139 
Align Right 45, 139 
Align Top 45, 139 
Distribute Horizontally 46, 140 
Distribute Vertically 46, 140 
Hide Connections 44 
Match Height 46, 139 
Match Width 46, 139 
part code generation tool 44 
selection tool 44 
Show Connections 44 
Snap To Grid 45 
Toggle Grid 45 


trace, set up 275 

translation, using resource files 293 
type list, showing 37 

10 type, change variable 164 

U 

undo changes 160 

undo delete 135 

unload files 34 

unload mouse pointer 43, 127 

update 

action 72 
attribute 62 
event 67 

promoted feature 74 
user .cpv file field 56 
user .h file field 56 
user .hpv file field 56 
user .rev file field 56 
user error 192 

user files included in generation group box 56 
using inheritance 86 
using parts 115 

V 

variable 

promoted, connecting to part 270 
variable part, connect 206 
variable type, change 164 
variable, add to composite part 163 
variable, add to part interface 165 
vbb files 33 
add part 291 
copy part to another 123 
delete part 125 
include part 53 
move part 53, 123 
oanonvis 90, 161 
oawin 90 
rename part 126 
vbbase.vbb file 4 
vbpalet.dat 292 
Visual Builder 
benefits 3 
concepts 

connections 4 
parts 4 

source code generation 5 
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Visual Builder (continued) 

creating to-do list application 7 
to-do list 7 
editors 41 
exiting 23 
starting 

from OS/2 26 
from tools folder 8, 27 
from WorkFrame 27 
use existing code with 281 
Visual Builder window 8, 27, 31 
visual components 
action page 57 
attribute page 57 
event page 57 
preferred page 58 
promote page 57 
visual part 

See also part 

adding basic to GUI 161 
changing labels 162 
changing settings 162 
creating for to-do list 9 
edit on free-form surface 153 
generating source code 20, 217 
lay out 42 
oawin.vbb 90 

supplementary composite, placing 130 
use to construct GUI 115 
using Composition Editor 42 
visually construct application 115 

W 

window 

Action Page of the Part Interface Editor 70 

add palette category 287 

add to palette 289, 290, 291 

attribute page of the Part Interface Editor 58 

Change Name Request 136 

composite part used as subpart 132 

Delete Parts 125 

Event Page of the Part Interface Editor 65 

File — Load 34 

incomplete connection 180 

multiple parts selected 133 

Part — New 9, 87 

Part — New window 119 

Preferred page of the Part Interface Editor 76 

promote page of the Part Interface Editor 73 


window (continued) 

promoting features for a push button part 157 
resizing application 14 
Tabbing And Depth Order 149 
Unload Part Files 35 
using an attribute as the input value 181 
Visual Builder 8, 27, 31 
window, settings 194 

work with part classes in Visual Builder window 
WorkFrame makemake program 272 


working directory 

setting 39 


todolist.app 

21 

todolist.cpp 

21 

todolist.exe 

21 

todolist.h 21 

todolist.hpp 

21 

todolist.mak 

21 

todolist.map 

21 

todolist.o 21 

todolist.obj 

22 

todolist.rc 21 

todolist.res 

22 

todolst2.app 

218 

todolst2.cpp 

217 

todolst2.exe 

218 

todolst2.h 217 

todolst2.hpp 

217 

todolst2.mak 

218 

todolst2.map 

218 

todolst2.o 218 

todolst2.obj 

218 

todolst2.rc 

217 

todolst2.res 

218 


working directory, setting 39 
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